agentic-api 2.0.314 → 2.0.491

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

@@ -321,7 +321,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 = 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;
@@ -407,6 +407,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 +435,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 +595,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/types.d.ts

@@ -510,3 +510,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.js

@@ -53,9 +53,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 +130,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,6 +147,10 @@ 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`;

package/dist/src/scrapper.js

@@ -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
      */

package/dist/src/stategraph/stategraph.js

@@ -41,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)
      */
@@ -83,8 +91,14 @@ class AgentStateGraph {
     }
     /**
      * 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, step) {
         const discussion = this.discussions.find(d => d.startAgent === agentName);
@@ -158,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
      */
@@ -170,8 +195,23 @@ class AgentStateGraph {
             return content;
         };
         // 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.role !== 'tool' && !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,
@@ -184,6 +224,7 @@ class AgentStateGraph {
             description: discussion.description,
             agent: agentName,
             messages: clientMessages,
+            steps: [...discussion.trailSteps],
             usage: discussion.usage,
             createdAt: discussion.createdAt,
             updatedAt: discussion.updatedAt

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

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
@@ -146,6 +149,8 @@ export interface ClientDiscussion {
         content: string;
         timestamp: Date;
     }>;
+    /** Context trail steps (actions effectuées) */
+    steps: StepTrail[];
     /** Usage des tokens */
     usage: TokenUsage;
     /** Dates */

package/dist/src/types.d.ts

@@ -9,12 +9,20 @@ export interface ToolParameterProperty {
     required?: string[];
     additionalProperties?: boolean;
     items?: ToolParameterProperty;
+    minLength?: number;
+    maxLength?: number;
+    format?: string;
+    minimum?: number;
+    maximum?: number;
+    default?: any;
+    [key: string]: any;
 }
 export interface ToolParameters {
     type: string;
     properties: Record<string, ToolParameterProperty>;
     required?: string[];
     additionalProperties?: boolean;
+    [key: string]: any;
 }
 export interface Tool {
     type: "function";
@@ -25,6 +33,17 @@ export interface Tool {
         strict: boolean;
     };
 }
+export type ToolContractOutput<T> = {
+    status: "ok" | "success" | "empty" | "error" | "transfer_required" | "multiple_results";
+    items?: T[];
+    meta?: Record<string, any>;
+    control?: {
+        next_hint?: string;
+        can_retry: boolean;
+        error_code?: string;
+        transfer_message?: string;
+    };
+};
 export interface AgentModelMapping {
     [key: string]: string;
 }
@@ -35,16 +54,30 @@ export interface AgentModel {
     topP?: number;
     stream?: boolean;
     parallel_tool_calls: boolean;
-    frequencyPenalty?: number;
-    presencePenalty?: number;
     stop?: string[] | string;
     tool_choice?: "auto" | "none" | "required";
     /**
      * Timeout in milliseconds for a query.
-     * If not specified, the default  (10 minutes).
+     * If not specified, the default (10 minutes).
      * https://platform.openai.com/docs/guides/flex-processing#api-request-timeouts
      */
     timeout?: number;
+    verbosity?: string;
+    reasoning_effort?: string;
+    frequencyPenalty?: number;
+    presencePenalty?: number;
+    text?: {
+        verbosity?: string;
+        format?: {
+            type: string;
+            name?: string;
+            schema?: any;
+            strict?: boolean;
+        };
+    };
+    reasoning?: {
+        effort: string;
+    };
 }
 export interface AgentConfig {
     name: string;
@@ -85,6 +118,7 @@ export interface AgenticContext {
     session: any;
     [key: string]: any;
     currentAgent?: AgentConfig;
+    discussionRootAgent?: string;
 }
 export type AllAgentConfigsType = Record<string, AgentConfig[]>;
 export interface Usage {
@@ -130,7 +164,8 @@ export interface ExecutionAction {
  * - `lastMessage`: The final assistant message content after execution.
  * - `usage`: Token usage/cost snapshot for the whole execution.
  * - `error`: Optional error message if something went wrong (non-fatal).
- * - `moreThinkin`: When true, caller should continue the execution loop (retro-compat flag).
+ *
+ * NOTE: `moreThinkin` was removed (obsolete) - reasoning_effort in modelConfig handles this natively
  */
 export interface ExecutionResult {
     runId: string;
@@ -140,7 +175,6 @@ export interface ExecutionResult {
     lastMessage: string;
     usage: Usage;
     error?: string;
-    moreThinkin: boolean;
     /**
      * Human-readable summary formatter. Optional to preserve backward compatibility.
      */
@@ -152,10 +186,11 @@ export interface ExecutionResult {
  * Merge strategy:
  * - `runId`: preserved from the primary accumulator `a`.
  * - `actions`: appended in order (a.actions then b.actions).
- * - `lastMessage`: preserved from `a` unless set elsewhere later in the workflow.
+ * - `lastMessage`: prioritize more recent (b) over older (a).
  * - `usage`: summed field-by-field to accumulate totals across steps.
  * - `error`: keep the latest non-undefined error (prefer `b`).
- * - `moreThinkin`: true if either `a` or `b` requests continued thinking.
+ *
+ * NOTE: moreThinkin removed (obsolete) - always returns false
  */
 export declare function enrichExecutionResult(result: ExecutionResult): ExecutionResult;
 export declare function executionResultMerge(a: ExecutionResult, b: ExecutionResult): ExecutionResult;

package/dist/src/types.js

@@ -8,10 +8,11 @@ exports.executionResultMerge = executionResultMerge;
  * Merge strategy:
  * - `runId`: preserved from the primary accumulator `a`.
  * - `actions`: appended in order (a.actions then b.actions).
- * - `lastMessage`: preserved from `a` unless set elsewhere later in the workflow.
+ * - `lastMessage`: prioritize more recent (b) over older (a).
  * - `usage`: summed field-by-field to accumulate totals across steps.
  * - `error`: keep the latest non-undefined error (prefer `b`).
- * - `moreThinkin`: true if either `a` or `b` requests continued thinking.
+ *
+ * NOTE: moreThinkin removed (obsolete) - always returns false
  */
 function enrichExecutionResult(result) {
     const formatAction = (action, index) => {
@@ -29,7 +30,7 @@ function enrichExecutionResult(result) {
         if (result.error) {
             lines.push(`error: ${result.error}`);
         }
-        lines.push(`moreThinkin: ${Boolean(result.moreThinkin)}`);
+        // moreThinkin removed (obsolete) - reasoning_effort fait le job
         const actions = result.actions || [];
         lines.push(`actions (${actions.length}):`);
         actions.forEach((a, i) => lines.push(`  - ${formatAction(a, i)}`));
@@ -42,16 +43,16 @@ function executionResultMerge(a, b) {
     const merged = {
         runId: a.runId && a.runId.length > 0 ? a.runId : b.runId,
         startQuery: a.startQuery || b.startQuery || '',
-        actions: [],
-        lastMessage: a.lastMessage || '',
+        actions: [...(a.actions || []), ...(b.actions || [])], // ✅ BUG FIX: Fusionner les actions
+        lastMessage: b.lastMessage || a.lastMessage || '', // ✅ BUG FIX: Prioriser le plus récent (b)
         usage: {
             prompt: (a.usage?.prompt || 0) + (b.usage?.prompt || 0),
             completion: (a.usage?.completion || 0) + (b.usage?.completion || 0),
             total: (a.usage?.total || 0) + (b.usage?.total || 0),
             cost: (a.usage?.cost || 0) + (b.usage?.cost || 0),
         },
-        error: b.error ?? a.error,
-        moreThinkin: Boolean(a.moreThinkin || b.moreThinkin),
+        error: b.error ?? a.error
+        // moreThinkin removed (obsolete) - reasoning_effort fait le job
     };
     return enrichExecutionResult(merged);
 }

package/dist/src/usecase.js

@@ -24,7 +24,7 @@ async function llmExtractUserQueries(inputsection, file, options = { model: "LOW
     // response_format: { type: "json_object" }
     const result = await (0, execute_1.executeQuery)({
         query,
-        home: options.model,
+        model: options.model,
         stdout: execute_1.DummyWritable,
         verbose: false,
         json: true

package/dist/src/utils.js

@@ -15,8 +15,10 @@ const openaiInstance = function (envKey, baseUrl) {
     if (!envKey) {
         throw new Error('AI API key is missing');
     }
+    // 
+    // use multiple fallback if envKey is not set
     const options = {
-        apiKey: process.env[envKey],
+        apiKey: process.env[envKey] || envKey || process.env.API_LLM_KEY || process.env.OPENAI_API_KEY,
         timeout: 60000 * 15
     };
     if (baseUrl) {
@@ -152,6 +154,14 @@ ${availableAgentsList}
 //
 // Fonction pour gérer un appel de fonction retourné par OpenAI
 // le contexte est un objet qui contient des informations supplémentaires de session
+//
+// TODO [Phase 2 - openai-agents-js]: 
+// Cette logique de handleTransferCall sera remplacée par le handoff natif
+// de openai-agents-js (https://openai.github.io/openai-agents-js/)
+// qui gère les transferts via policies et router intégrés.
+// Les concepts de downstreamAgents et confidence seront mappés 
+// vers les primitives de l'Agent SDK (swarm.run, handoff strategies).
+// Le stateGraph restera compatible car il utilise AgentMessage générique.
 async function handleTransferCall(discussion, currentAgentRef, agents, functionCallParams, context) {
     const currentAgentName = currentAgentRef.name;
     const args = JSON.parse(functionCallParams?.function?.arguments || '{}');
@@ -199,6 +209,7 @@ async function handleTransferCall(discussion, currentAgentRef, agents, functionC
             return {
                 feedback: `❌ L'agent destination "${destinationAgentName}" n'a pas été trouvé.`,
                 content: `❌L'agent destination "${destinationAgentName}" n'a pas été trouvé.`,
+                context: `❌L'agent destination "${destinationAgentName}" n'a pas été trouvé.`,
                 did_transfer: false,
                 name: functionCallParams.function.name
             };
@@ -219,11 +230,24 @@ async function handleTransferCall(discussion, currentAgentRef, agents, functionC
     // ⚠️ ALWAYS inject context in tool logic, ALWAYS!
     const agent = agents.find(a => a.name === currentAgentRef.name);
     if (agent?.toolLogic && agent.toolLogic[functionCallParams.function.name]) {
-        const { content, usage } = await agent.toolLogic[functionCallParams.function.name](args, context);
+        const rawResult = await agent.toolLogic[functionCallParams.function.name](args, context);
+        //
+        // ✅ Le tool peut retourner { content, context, id, usage? } OU ToolContractOutput
+        // - Si content existe → utiliser le texte formaté
+        // - Sinon → préserver rawResult pour sérialisation (ToolContractOutput)
+        // - context: identifiant sémantique unique pour le trail (ex: "intention_123", "daily-events")
+        // - id: slug unique pour détection de boucles (généralement dérivé du context)
+        // Si le tool ne fournit pas context/id, on utilise le nom du tool comme fallback
+        const toolContext = rawResult.context || 'Null';
+        const toolId = rawResult.id || args.justification || JSON.stringify(args);
         return {
-            content,
+            content: rawResult.content, // ✅ Peut être undefined pour ToolContractOutput
             name: functionCallParams.function.name,
-            usage
+            context: toolContext,
+            id: toolId,
+            usage: rawResult.usage,
+            feedback: rawResult.feedback,
+            rawResult: rawResult // ✅ Préserver le résultat brut pour sérialisation
         };
     }
     else {