agentic-api 2.0.31 → 2.0.491

package/dist/src/scrapper.js

@@ -4,8 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractCaptcha = extractCaptcha;
-exports.callGPTForParsingPDF = callGPTForParsingPDF;
-exports.callGPTForParsingHTML = callGPTForParsingHTML;
+exports.callLLMForParsingPDF = callLLMForParsingPDF;
 exports.html2markdown = html2markdown;
 exports.pdf2markdown = pdf2markdown;
 const child_process_1 = require("child_process");
@@ -14,9 +13,11 @@ const path_1 = __importDefault(require("path"));
 const fs_1 = __importDefault(require("fs"));
 const jsdom_1 = require("jsdom");
 const readability_1 = require("@mozilla/readability");
-const princing_openai_1 = require("./princing.openai");
+const pricing_llm_1 = require("./pricing.llm");
 const prompts_1 = require("./prompts");
 const utils_1 = require("./utils");
+const execute_1 = require("./execute");
+const utils_matter_1 = require("./rules/utils.matter");
 // Promisify exec for easier async/await usage
 const execAsync = (0, util_1.promisify)(child_process_1.exec);
 const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
@@ -36,7 +37,7 @@ async function extractCaptcha(base64Image, openai) {
         messages: [{ role: "user", content }],
         max_completion_tokens: 50,
     });
-    const cost = (0, princing_openai_1.calculateCost)(model, response.usage);
+    const cost = (0, pricing_llm_1.calculateCost)(model, response.usage);
     // Récupérer la réponse markdown
     const number = response.choices[0].message.content;
     return { number, cost };
@@ -46,11 +47,11 @@ async function extractCaptcha(base64Image, openai) {
  *
  * @param {string} inputfile - The name of the PDF file being processed
  * @param {any} pdfData - The extracted content from the PDF file
- * @param {any} openai - The OpenAI client instance
  * @param {any[]} links - Optional array of links extracted from the PDF to be integrated into the markdown
+ * @param {string} model - The model to use for parsing (default: "MEDIUM-fast")
  * @returns {Promise<{markdown: string, cost: number}>} - The parsed markdown content and the cost of the API call
  */
-async function callGPTForParsingPDF(inputfile, pdfData, openai, links = []) {
+async function callLLMForParsingPDF(inputfile, pdfData, links = [], model = "MEDIUM-fast") {
     // Convertir le contenu en chaîne de caractères (attention à la taille potentielle !)
     const pdfDataAsString = JSON.stringify(pdfData, null, 2);
     // Format: YYYY-MM-DD
@@ -62,57 +63,25 @@ async function callGPTForParsingPDF(inputfile, pdfData, openai, links = []) {
     // Créer le prompt pour décrire la tâche au LLM
     const messages = [
         { role: "system",
-            content: prompts_1.htmlToMarkdownPrompt },
-        { role: "user",
-            content: `Structure le contenu  exhaustif en Markdown sans rien inventer, et avec les liens intégrés correctement.\n Nous sommes le ${today}.\n${linkPrefix}\nLe contenu du document est:\n${pdfDataAsString}`
-        }
+            content: prompts_1.htmlToMarkdownPrompt }
     ];
-    // console.log('🌶️ DEBUG: callGPTForParsingPDF -- SYSTEM:', messages[0].content);
-    // console.log('🌶️ DEBUG: callGPTForParsingPDF -- USER:', messages[1].content);
+    // console.log('🌶️ DEBUG: callLLMForParsingPDF -- SYSTEM:', messages[0].content);
+    // console.log('🌶️ DEBUG: callLLMForParsingPDF -- USER:', messages[1].content);
     // WARNING: o3-mini is buggy with "Marche à suivre nouveau bail.pdf"
-    const model = "gpt-4.1"; // "gpt-4.1";
-    let response = await openai.chat.completions.create({
-        model: model,
+    const response = await (0, execute_1.executeQuery)({
+        query: `Structure le contenu  exhaustif en Markdown sans rien inventer, et avec les liens intégrés correctement.\n Nous sommes le ${today}.\n${linkPrefix}\nLe contenu du document est:\n${pdfDataAsString}`,
+        model,
         messages,
+        stdout: execute_1.DummyWritable,
+        verbose: false
     });
-    // response_format: { type: "json_object" }
-    let cost = (0, princing_openai_1.calculateCost)(model, response.usage);
-    // messages.push({
-    //     role: "user",
-    //     content: `Maintenant génère le contenu Markdown détaillé et exhaustif correspondant à chaque section avec les liens intégrés correctement.`
-    // });
-    // response = await openai.chat.completions.create({
-    //   model: model,
-    //   messages,
-    //   max_completion_tokens: 15192,
-    //   reasoning_effort:"low",
-    //   stop:"|<|james|>|"
-    // });
     // Récupérer la réponse markdown
-    let markdown = response.choices[0].message.content;
-    console.log(`Markdown 💰 cost: ${cost}`);
+    const markdown = response.content;
+    console.log(`Markdown 💰 cost: ${response.usage.cost}`);
     //
     // add a regex to extract the markdown content between <thinking></thinking> tags
-    let markdownWithoutThinking = markdown.replace(/<thinking>[\s\S]*?<\/thinking>/g, '');
-    // const hragPrompt = await extractHRAGSections(markdownWithoutThinking, openai);
-    // messages.push({
-    //   role: "user",
-    //   content: hragPrompt
-    // });
-    // response = await openai.chat.completions.create({
-    //   model: model,
-    //   messages,
-    //   max_completion_tokens: 15192,
-    //   reasoning_effort:"low",
-    //   stop:"|<|james|>|"
-    // });
-    // // Récupérer la réponse markdown
-    // markdown = response.choices[0].message.content;
-    // cost += calculateCost(model, response.usage);
-    // //
-    // // add a regex to extract the markdown content between <thinking></thinking> tags
-    // markdownWithoutThinking = markdown.replace(/<thinking>[\s\S]*?<\/thinking>/g, '');
-    return { markdown: markdownWithoutThinking, cost };
+    const markdownWithoutThinking = markdown.replace(/<thinking>[\s\S]*?<\/thinking>/g, '');
+    return { markdown: markdownWithoutThinking, cost: response.usage.cost };
 }
 /**
  * Extracts hyperlinks from a PDF file by converting it to HTML and parsing the links.
@@ -156,47 +125,6 @@ async function extractLinksFromPDF(pdfPath, output) {
         }
     }
 }
-/**
- * Convertit un document HTML en markdown en appelant le modèle GPT (ex: gpt-4.1)
- * pour analyser et reformater le document.
- *
- * @param {any} htmlData - Le document HTML à transformer en markdown.
- * @param {any} openai - L'instance OpenAI configurée pour appeler l'API.
- * @param {boolean} simple - Si true, utilise un prompt simplifié.
- * @returns {Promise<Object>} - Le contenu markdown structuré créé par le modèle LLM.
- */
-async function callGPTForParsingHTML(html, openai) {
-    const htmlDataAsString = html;
-    // Créer le prompt pour décrire la tâche au LLM
-    const messages = [
-        {
-            role: "system",
-            content: prompts_1.htmlToMarkdownPrompt
-        },
-        {
-            role: "user",
-            content: `Voici le document HTML à transformer en markdown : \n${htmlDataAsString}`
-        }
-    ];
-    // Appel à l'API ChatCompletion
-    const response = await openai.chat.completions.create({
-        model: "gpt-4.1",
-        messages,
-        max_completion_tokens: 15192,
-        temperature: 0,
-        frequency_penalty: 0.0,
-        presence_penalty: 0.0,
-    });
-    const cost = (0, princing_openai_1.calculateCost)("gpt-4.1", response.usage);
-    console.log(`Markdown 💰 cost: ${cost}`);
-    // Récupérer la réponse markdown
-    const markdown = response.choices[0].message.content;
-    if (!markdown)
-        throw new Error("No markdown found");
-    // Extraction et suppression des balises <thinking></thinking>
-    const markdownWithoutThinking = markdown.replace(/<thinking>[\s\S]*?<\/thinking>/g, '');
-    return markdownWithoutThinking;
-}
 function cleanHTML(html) {
     const dom = new jsdom_1.JSDOM(html);
     // Instancie Readability avec le document
@@ -210,15 +138,15 @@ function cleanHTML(html) {
  * @param {string} output - The directory path where the output markdown file will be saved.
  * @param {string} file - The path to the HTML file to be parsed.
  * @param {string} service - The service name used as part of the output filename output.
- * @param {any} openai - The OpenAI instance to use for the GPT API calls.
+ * @param {string} model - The model to use for parsing (default: "MEDIUM-fast")
  * @returns {Promise<{markdown: string, cost: number}>} - The generated markdown content and the cost of the GPT API call.
  */
-async function html2markdown(output, file, service, openai) {
+async function html2markdown(output, file, service, model = "MEDIUM-fast") {
     const filename = (0, utils_1.toSlug)(path_1.default.basename(file, path_1.default.extname(file)));
     const htmlraw = fs_1.default.readFileSync(file, "utf8");
     const html = cleanHTML(htmlraw);
     const outputfile = html.indexOf('Please sign in') > -1 ? 'unauthorized-' : (service.toLocaleLowerCase() + '-');
-    const { markdown, cost } = await callGPTForParsingPDF(file, html, openai);
+    const { markdown, cost } = await callLLMForParsingPDF(file, html, [], model);
     fs_1.default.writeFileSync(path_1.default.join(output, `${outputfile + filename}.md`), markdown, { encoding: 'utf8', flag: 'w' });
     return { markdown, cost };
 }
@@ -226,32 +154,52 @@ async function html2markdown(output, file, service, openai) {
  * Parse un PDF en effectuant :
  * 1. Le nettoyage du PDF avec Ghostscript.
  * 2. Sa conversion en XML via pdftohtml.
- * 3. (Optionnellement) Le passage du contenu converti au modèle GPT pour analyser la structure.
+ * 3. (Optionnellement) Le passage du contenu converti au modèle LLM pour analyser la structure.
  *
- * @param {string} file - Chemin vers le fichier PDF à analyser.
- * @param {any} openai - L'instance configurée pour appeler l'API OpenAI.
- * @returns {Promise<any>} - Le markdown structuré (issue de GPT) ou tout autre traitement souhaité.
+ * @param {string} outputDir - Dossier de sortie pour le fichier markdown.
+ * @param {string} pdf - Chemin vers le fichier PDF à analyser.
+ * @param {FrontMatter|null} matter - Métadonnées du document (title, service, author, role). Si null, utilise le nom du PDF pour le titre.
+ * @param {string} model - Le modèle à utiliser (défaut: "MEDIUM-fast").
+ * @returns {Promise<{markdown: string, cost: number, outputPath: string}>} - Le markdown structuré, le coût et le chemin du fichier de sortie.
  */
-async function pdf2markdown(folder, file, service, openai) {
-    const filename = (0, utils_1.toSlug)(path_1.default.basename(file, path_1.default.extname(file)));
+async function pdf2markdown(outputDir, pdf, matter, model = "MEDIUM-fast") {
+    //
+    // Extract matter values with defaults
+    const service = matter?.service || 'unknown';
+    const title = matter?.title || path_1.default.basename(pdf, path_1.default.extname(pdf));
+    //
+    // Build complete FrontMatter with defaults
+    const frontMatter = {
+        title,
+        service,
+        author: matter?.author || '',
+        role: matter?.role || 'rule',
+    };
+    //
+    // Use title for filename
+    const filename = (0, utils_1.toSlug)(title);
     // Créez des noms de fichiers temporaires pour le PDF nettoyé et le XML généré.
-    const tempPdf = path_1.default.join(folder, `cleaned-${randomFile()}.pdf`);
-    const tempOut = path_1.default.join(folder, `${filename}.txt`);
+    const tempPdf = path_1.default.join(outputDir, `cleaned-${randomFile()}.pdf`);
+    const tempOut = path_1.default.join(outputDir, `${filename}.txt`);
     //
     // generated folder path
-    const outputPath = path_1.default.join(folder, `${(0, utils_1.toSlug)(service.toLocaleLowerCase())}-${filename}.md`);
+    const outputPath = path_1.default.join(outputDir, `${(0, utils_1.toSlug)(service.toLocaleLowerCase())}-${filename}.md`);
     try {
         //
         // replace pdftotext with python script PyMuPDF
         // Ca ne marche pas mieux que pdftotext
-        // const { stdout } = await execFileAsync("python3", ["./bin/extract_text_with_links.py", file]);
+        // const { stdout } = await execFileAsync("python3", ["./bin/extract_text_with_links.py", pdf]);
         // const { text, links } = JSON.parse(stdout);
-        await execAsync(`pdftotext -nodiag -nopgbrk "${file}" "${outputPath}"`);
-        const links = await extractLinksFromPDF(file, folder);
+        // `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");
-        const { markdown, cost } = await callGPTForParsingPDF(file, text, openai, links);
-        fs_1.default.writeFileSync(outputPath, markdown);
-        return { markdown, cost, outputPath };
+        const { markdown, cost } = await callLLMForParsingPDF(pdf, text, links, model);
+        //
+        // Add frontmatter to the markdown before saving
+        const markdownWithMatter = (0, utils_matter_1.matterSerialize)(markdown, frontMatter);
+        fs_1.default.writeFileSync(outputPath, markdownWithMatter);
+        return { markdown: markdownWithMatter, cost, outputPath };
         /**
     
         // STEP 1: Clean the PDF using Ghostscript.
@@ -271,7 +219,7 @@ async function pdf2markdown(folder, file, service, openai) {
     
         // (OPTIONNEL) STEP 3: Utilisez GPT pour analyser la structure du contenu XML.
         // Vous pouvez adapter le traitement en fonction du contenu généré par pdftohtml.
-        const {markdown,cost} = await callGPTForParsingPDF(file, xmlContent, openai);
+        const {markdown,cost} = await callLLMForParsingPDF(file, xmlContent, [], model);
         fs.writeFileSync(outputPath, markdown);
         return {markdown,cost}; */
     }

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

@@ -2,7 +2,7 @@
  * @fileoverview Point d'entrée du module AgentStateGraph
  * Exports principaux pour le système de gestion des discussions par agent
  */
-export type { AgentMessage, TokenUsage, AgentDiscussion, AgentStateGraph as IAgentStateGraph, ClientDiscussion } from './types';
+export type { AgentMessage, TokenUsage, AgentDiscussion, ClientDiscussion } from './types';
 export { getSpecializedAgent } from './types';
 export { AgentStateGraph } from './stategraph';
 export { sessionStateGraphGet, sessionStateGraphSet, sessionStateGraphClear, sessionStateGraphExists, sessionStateGraphSize, migrateFromLegacySession } from './stategraph.storage';

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

@@ -2,7 +2,7 @@
  * @fileoverview Implémentation du système AgentStateGraph
  * Classe principale pour gérer les discussions par agent
  */
-import { AgentStateGraph as IAgentStateGraph, AgentDiscussion, AgentMessage, TokenUsage, ClientDiscussion } from './types';
+import { AgentStateGraph as IAgentStateGraph, AgentDiscussion, AgentMessage, TokenUsage, ClientDiscussion, StepTrail } from './types';
 /**
  * Implémentation du StateGraph pour la gestion des discussions par agent
  * Remplace AgenticMemoryManager avec une architecture simplifiée
@@ -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)
      */
@@ -24,10 +32,39 @@ export declare class AgentStateGraph implements IAgentStateGraph {
     /**
      * Écrase le message system de la discussion avec un nouvel agent
      * Le message system est toujours messages[0] avec role: "system"
-     * @param agentName Nom de l'agent
+     * @param agentName Nom de l'agent (clé de discussion, reste fixe)
      * @param content Nouveau contenu du message system
      */
     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 (tool, context, reason, id optionnel)
+     */
+    addStep(agentName: string, step: StepTrail): void;
+    /**
+     * Retourne tous les steps du CONTEXT TRAIL pour une discussion
+     * @param agentName Nom de l'agent
+     * @returns Liste des steps enregistrés pour cette discussion
+     */
+    steps(agentName: string): StepTrail[];
+    /**
+     * Formate le CONTEXT TRAIL d'une discussion pour injection dans system instructions
+     * @param discussion Discussion à formater
+     * @returns Trail formaté ou message par défaut
+     */
+    private formatTrailPrompt;
+    /**
+     * Met à jour le message system avec le nouveau trail via regexp
+     * @param agentName Nom de l'agent
+     */
+    private updateSystemMessage;
     /**
      * Additionne l'usage des tokens pour un agent
      * @param agentName Nom de l'agent
@@ -37,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
      */
@@ -78,6 +126,12 @@ export declare class AgentStateGraph implements IAgentStateGraph {
      * @returns Nom de l'agent spécialisé
      */
     getSpecializedAgent(agentName: string): string;
+    /**
+     * Charge une discussion en remplaçant l'existante ou en créant une nouvelle
+     * Recherche par id en priorité, sinon par startAgent
+     * @param discussion Discussion à charger
+     */
+    load(discussion: AgentDiscussion): void;
     /**
      * Sérialise le StateGraph en JSON
      * @returns Représentation JSON

package/dist/src/stategraph/stategraph.js

@@ -30,6 +30,7 @@ class AgentStateGraph {
                 description: description,
                 messages: [],
                 usage: { prompt: 0, completion: 0, total: 0, cost: 0 },
+                trailSteps: [], // ✅ Chaque discussion a son propre trail
                 createdAt: new Date(),
                 updatedAt: new Date(),
                 startAgent: agentName
@@ -40,6 +41,14 @@ class AgentStateGraph {
     }
     /**
      * 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)
      */
@@ -56,7 +65,7 @@ class AgentStateGraph {
     /**
      * Écrase le message system de la discussion avec un nouvel agent
      * Le message system est toujours messages[0] avec role: "system"
-     * @param agentName Nom de l'agent
+     * @param agentName Nom de l'agent (clé de discussion, reste fixe)
      * @param content Nouveau contenu du message system
      */
     set(agentName, content) {
@@ -64,8 +73,8 @@ class AgentStateGraph {
         const systemMessage = {
             id: (0, crypto_1.randomUUID)(),
             role: 'system',
-            content,
-            agent: agentName,
+            content: content,
+            agent: agentName, // Tag avec la clé de discussion
             timestamp: new Date()
         };
         // Écraser ou créer le message system (toujours en position 0)
@@ -73,8 +82,75 @@ class AgentStateGraph {
             discussion.messages.push(systemMessage);
         }
         else {
-            discussion.messages[0] = systemMessage;
+            discussion.messages[0].content = content;
+            discussion.messages[0].agent = systemMessage.agent;
+            discussion.messages[0].timestamp = new Date();
         }
+        this.updateSystemMessage(discussion);
+        discussion.updatedAt = new Date();
+    }
+    /**
+     * 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 (tool, context, reason, id optionnel)
+     */
+    addStep(agentName, step) {
+        const discussion = this.discussions.find(d => d.startAgent === agentName);
+        if (!discussion)
+            return;
+        discussion.trailSteps.push(step);
+        this.updateSystemMessage(discussion);
+    }
+    /**
+     * Retourne tous les steps du CONTEXT TRAIL pour une discussion
+     * @param agentName Nom de l'agent
+     * @returns Liste des steps enregistrés pour cette discussion
+     */
+    steps(agentName) {
+        const discussion = this.discussions.find(d => d.startAgent === agentName);
+        // console.log(`🔍 steps: ${agentName} has ${discussion?.trailSteps.length} steps`);
+        return discussion ? [...discussion.trailSteps] : [];
+    }
+    /**
+     * Formate le CONTEXT TRAIL d'une discussion pour injection dans system instructions
+     * @param discussion Discussion à formater
+     * @returns Trail formaté ou message par défaut
+     */
+    formatTrailPrompt(discussion) {
+        if (discussion.trailSteps.length === 0) {
+            return '(No actions yet)';
+        }
+        return discussion.trailSteps.map(s => {
+            const idPart = s.id ? ` [id: ${s.id}]` : '';
+            return `- ${s.tool}: ${s.context} "${s.reason}"${idPart}`;
+        }).join('\n');
+    }
+    /**
+     * Met à jour le message system avec le nouveau trail via regexp
+     * @param agentName Nom de l'agent
+     */
+    updateSystemMessage(discussion) {
+        const systemMessage = discussion.messages.find((m) => m.role === 'system');
+        if (!systemMessage)
+            return;
+        const trail = this.formatTrailPrompt(discussion);
+        const trailBlock = `<context-trail>\n${trail}\n</context-trail>`;
+        const hasTag = systemMessage.content.includes('<context-trail>');
+        // Remplacement via regexp du tag <context-trail>
+        if (hasTag) {
+            systemMessage.content = systemMessage.content.replace(/<context-trail>[\s\S]*?<\/context-trail>/, trailBlock);
+        }
+        else {
+            // Ajouter le tag si absent
+            systemMessage.content += `\n\n${trailBlock}`;
+        }
+        systemMessage.timestamp = new Date();
         discussion.updatedAt = new Date();
     }
     /**
@@ -96,6 +172,17 @@ class AgentStateGraph {
     /**
      * 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
      */
@@ -107,9 +194,24 @@ class AgentStateGraph {
             }
             return content;
         };
-        // Filtrer les messages pour le client - exclure system et tool
+        // Filtrer les messages pour le client - exclure system, tool et messages avec name
+        // ✅ Exclure aussi les messages Responses API (type: "function_call_output") et tool_calls sans content
         const clientMessages = discussion.messages
-            .filter(msg => msg.role !== 'system' && !msg.name)
+            .filter((msg) => {
+            // Exclure system et tool
+            if (msg.role === 'system' || msg.role === 'tool')
+                return false;
+            // Exclure messages avec name (Chat Completions function results)
+            if (msg.name)
+                return false;
+            // Exclure messages Responses API: function_call_output
+            if (msg.type === 'function_call_output')
+                return false;
+            // Exclure messages assistant avec tool_calls mais sans content (métadonnées de tools)
+            if (msg.tool_calls && msg.tool_calls.length > 0 && !msg.content)
+                return false;
+            return true;
+        })
             .map(msg => ({
             id: msg.id,
             role: msg.role,
@@ -122,6 +224,7 @@ class AgentStateGraph {
             description: discussion.description,
             agent: agentName,
             messages: clientMessages,
+            steps: [...discussion.trailSteps],
             usage: discussion.usage,
             createdAt: discussion.createdAt,
             updatedAt: discussion.updatedAt
@@ -162,6 +265,7 @@ class AgentStateGraph {
             discussion.messages = [];
         }
         // Réinitialiser l'usage
+        discussion.trailSteps = [];
         discussion.usage = { prompt: 0, completion: 0, total: 0, cost: 0 };
         discussion.updatedAt = new Date();
     }
@@ -211,6 +315,29 @@ class AgentStateGraph {
         }
         return agentName;
     }
+    /**
+     * Charge une discussion en remplaçant l'existante ou en créant une nouvelle
+     * Recherche par id en priorité, sinon par startAgent
+     * @param discussion Discussion à charger
+     */
+    load(discussion) {
+        // Chercher discussion existante par id OU par startAgent
+        const index = this.discussions.findIndex(d => d.id === discussion.id || d.startAgent === discussion.startAgent);
+        if (index >= 0) {
+            // Remplacer l'existante
+            this.discussions[index] = {
+                ...discussion,
+                updatedAt: new Date()
+            };
+        }
+        else {
+            // Créer nouvelle
+            this.discussions.push({
+                ...discussion,
+                updatedAt: new Date()
+            });
+        }
+    }
     /**
      * Sérialise le StateGraph en JSON
      * @returns Représentation JSON
@@ -230,6 +357,7 @@ class AgentStateGraph {
                 ...d,
                 createdAt: new Date(d.createdAt),
                 updatedAt: new Date(d.updatedAt),
+                trailSteps: d.trailSteps || [], // ✅ Rétrocompatibilité : initialiser vide si absent
                 messages: d.messages.map((m) => ({
                     ...m,
                     timestamp: new Date(m.timestamp)

package/dist/src/stategraph/stategraph.storage.js

@@ -22,6 +22,10 @@ const SESSION_STATEGRAPH_KEY = 'agentStateGraph';
  * @returns StateGraph existant ou nouveau
  */
 function sessionStateGraphGet(context) {
+    // ✅ Si un stateGraph est passé directement dans le contexte (mode sans session)
+    if (context.stateGraph && context.stateGraph instanceof stategraph_1.AgentStateGraph) {
+        return context.stateGraph;
+    }
     const session = context.session;
     if (!session) {
         // Pour les tests, retourner un nouveau StateGraph si pas de session
@@ -71,6 +75,10 @@ function sessionStateGraphSet(context, stateGraph) {
         const compressed = (0, zlib_1.gzipSync)(Buffer.from(jsonData, 'utf8'));
         // Stocker en base64 dans la session
         session[SESSION_STATEGRAPH_KEY] = compressed.toString('base64');
+        // Force express-session à marquer la session comme modifiée
+        if (typeof session.touch === 'function') {
+            session.touch();
+        }
         // Logging pour debug (taille avant/après compression)
         if (process.env.NODE_ENV === 'development') {
             const originalSize = Buffer.byteLength(jsonData, 'utf8');

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

@@ -19,6 +19,9 @@ export interface AgentMessage {
     agent?: string;
     /** Timestamp de création */
     timestamp: Date;
+    type?: string;
+    tool_call_id?: string;
+    output?: string;
 }
 /**
  * Usage des tokens et coût
@@ -33,6 +36,20 @@ export interface TokenUsage {
     /** Coût estimé en USD (optionnel) */
     cost?: number;
 }
+/**
+ * Step du CONTEXT TRAIL - trace une action significative
+ * Utilisé pour maintenir une mémoire de travail des actions effectuées par les outils
+ */
+export interface StepTrail {
+    /** Nom de l'outil (ex: "transferAgents", "database") */
+    tool: string;
+    /** Contexte de l'action (ex: "orientation → guess-word") */
+    context: string;
+    /** Justification/raison de l'action */
+    reason: string;
+    /** ID optionnel pour détection de boucles */
+    id?: string;
+}
 /**
  * Discussion d'agent - thread de messages pour un agent spécifique
  * Remplace l'ancienne AgenticMemorySession
@@ -48,6 +65,8 @@ export interface AgentDiscussion {
     messages: AgentMessage[];
     /** Usage des tokens pour cette discussion */
     usage: TokenUsage;
+    /** CONTEXT TRAIL - steps des actions significatives */
+    trailSteps: StepTrail[];
     /** Date de création */
     createdAt: Date;
     /** Date de dernière mise à jour */
@@ -104,6 +123,12 @@ export interface AgentStateGraph {
      * @returns true si le message a été supprimé, false s'il n'a pas été trouvé
      */
     deleteMessage(agentName: string, messageId: string): boolean;
+    /**
+     * Charge une discussion en remplaçant l'existante ou en créant une nouvelle
+     * Cherche par id OU par startAgent
+     * @param discussion Discussion à charger
+     */
+    load(discussion: AgentDiscussion): void;
 }
 /**
  * Vue client d'une discussion (filtrée)
@@ -124,6 +149,8 @@ export interface ClientDiscussion {
         content: string;
         timestamp: Date;
     }>;
+    /** Context trail steps (actions effectuées) */
+    steps: StepTrail[];
     /** Usage des tokens */
     usage: TokenUsage;
     /** Dates */