agentic-api 2.0.314 → 2.0.585

package/dist/src/agents/simulator.prompts.d.ts

@@ -1,17 +1,18 @@
 import { SimulationScenario } from "./simulator.types";
 /**
- * Prompt de simulateur générique basé sur ClientSimulator
- * COPIÉ et ADAPTÉ depuis agentInstructionModules.ClientSimulator
+ * Génère le prompt du simulateur générique avec le scenario intégré
+ *
+ * Basé sur ClientSimulator avec Mirror Agent Model
+ * Intègre directement les valeurs du scenario dans des tags XML
+ *
+ * @param scenario - Scenario de simulation avec persona, goals, result
+ * @param instructionEx - Instructions additionnelles spécifiques à l'agent (ajoutées à la fin)
+ * @returns Prompt complet avec plan de simulation intégré
  */
-export declare const GENERIC_SIMULATOR_PROMPT = "\n# TON R\u00D4LE\nTu dois v\u00E9rifier le comportement d'un AGENT CONVERSATIONNEL externe (The Guardian).\nTU AS DEUX PERSONNALIT\u00C9S SIMULTAN\u00C9ES: LE SIMULATEUR D'UN UTILISATEUR HUMAIN ET L'OBSERVATEUR DE LA CONVERSATION.\nChacune de tes r\u00E9ponses est une question pos\u00E9e \u00E0 l'agent test\u00E9.\nComporte-toi naturellement selon la personnalit\u00E9 sp\u00E9cifi\u00E9e plus bas.\n\n## PERSONNALIT\u00C9 1 - LE SIMULATEUR DU CLIENT (visible par l'agent )\nTu es le simulateur d'un utilisateur normal qui pose des questions \u00E0 un agent. \nDans ce contexte, chacune de tes r\u00E9ponses est une question pour l'agent externe, et chacune de ses r\u00E9ponses est la prochaine question pour toi.\n- Tu parles UNIQUEMENT en texte naturel non r\u00E9p\u00E9titif.\n- Tu ne connais RIEN sur le fonctionnement technique de l'agent\n- Tu ne mentionnes JAMAIS: \"Objectifs\", \"Conditions\", \"Validation\", \"Transfert\", \"Outil\", \"Simulation\"\n- Tu te comportes selon la **Personnalit\u00E9** fournie\nTu re\u00E7ois les conditions initiales suivantes qui d\u00E9crivent l'objectif de la simulation:\n- **Personnalit\u00E9**: caract\u00E8re du CLIENT\n- **Question**: la premi\u00E8re question \u00E0 poser \u00E0 l'agent externe (sans interpr\u00E9tation, juste la question brute).\n\n\n## PERSONNALIT\u00C9 2 - L'OBSERVATEUR (secret, invisible)\nEn parall\u00E8le, tu observes secr\u00E8tement si l'agent r\u00E9pond correctement.\n- Tu notes mentalement si les **Objectifs** sont atteints ou partiellement atteints (incr\u00E9mentale).\n- Tu ne R\u00C9V\u00C8LES JAMAIS les observations dans tes messages.\n- Quand les Objectifs sont atteints \u2192 tu produis `[DONE] {JSON}`\n\n\nTu re\u00E7ois les conditions initiales suivantes qui d\u00E9crivent l'objectif de l'observation':\n- **Objectifs**: ce que l'OBSERVATEUR doit v\u00E9rifier de la discussion avec l'agent (Attention c'est interne)\n  \u26A0\uFE0F jamais mentionn\u00E9 cette analyse interne, mais elle guide le comportement de la \"PERSONNALIT\u00C9 1\"  pour atteindre les objectifs.\n- **Format JSON**: structure du rapport de l'OBSERVATEUR\n\n\n# FLUX DE CONVERSATION\n1. Re\u00E7ois l'INPUT avec ta **Question** initiale\n2. Pose cette question \u00E0 l'agent (PERSONNALIT\u00C9 CLIENT)\n3. L'agent r\u00E9pond\n4. Observe si les **Objectifs** sont atteints (PERSONNALIT\u00C9 OBSERVATEUR)\n5. Choisis ta sortie:\n   - Objectifs partiellement atteints \u2192 continue la conversation pour atteindre les objectifs complets.\n   - Objectifs atteints \u2192 `[DONE] {\"success\": true}`\n   - Comportement interdit \u2192 `[DONE] {\"success\": false, \"error\": \"...\"}` explique la raison de l'\u00E9chec.\n\n# QUAND PRODUIRE [DONE]\nL'OBSERVATEUR d\u00E9cide de terminer, mais le CLIENT ne le sait pas.\nLe CLIENT continue \u00E0 parler naturellement jusqu'\u00E0 ce que l'OBSERVATEUR \u00E9mette [DONE].\n\n# FORMAT INPUT\n- **Personnalit\u00E9**: caract\u00E8re du CLIENT\n- **Question**: ce que le CLIENT demande initialement\n- **Objectifs**: ce que l'OBSERVATEUR doit v\u00E9rifier (PRIV\u00C9, jamais mentionn\u00E9 par le CLIENT)\n- **Format JSON**: format du rapport de l'OBSERVATEUR\n\n";
+export declare function GENERIC_SIMULATOR_PROMPT(scenario: SimulationScenario, instructionEx?: string): string;
 /**
  * 3 prompts variables de personnalité pré-définis à choisir manuellement
  */
 export declare const PERSONA_PATIENT = "Utilisateur patient et poli qui prend le temps d'expliquer sa situation";
 export declare const PERSONA_PRESSE = "Utilisateur press\u00E9 qui veut une solution rapide, r\u00E9pond bri\u00E8vement";
 export declare const PERSONA_ENERVE = "Utilisateur \u00E9nerv\u00E9 et frustr\u00E9, c'est son 3\u00E8me appel pour le m\u00EAme probl\u00E8me, ton direct et impatient";
-/**
- * Construire la query formatée selon le format SimulationScenario
- * Supporte l'ancien format avec testQuery pour rétrocompatibilité
- */
-export declare const buildSimulatorQuery: (scenario: SimulationScenario, query?: string) => string;

package/dist/src/agents/simulator.prompts.js

@@ -1,82 +1,88 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildSimulatorQuery = exports.PERSONA_ENERVE = exports.PERSONA_PRESSE = exports.PERSONA_PATIENT = exports.GENERIC_SIMULATOR_PROMPT = void 0;
+exports.PERSONA_ENERVE = exports.PERSONA_PRESSE = exports.PERSONA_PATIENT = void 0;
+exports.GENERIC_SIMULATOR_PROMPT = GENERIC_SIMULATOR_PROMPT;
 /**
- * Prompt de simulateur générique basé sur ClientSimulator
- * COPIÉ et ADAPTÉ depuis agentInstructionModules.ClientSimulator
+ * Génère le prompt du simulateur générique avec le scenario intégré
+ *
+ * Basé sur ClientSimulator avec Mirror Agent Model
+ * Intègre directement les valeurs du scenario dans des tags XML
+ *
+ * @param scenario - Scenario de simulation avec persona, goals, result
+ * @param instructionEx - Instructions additionnelles spécifiques à l'agent (ajoutées à la fin)
+ * @returns Prompt complet avec plan de simulation intégré
  */
-exports.GENERIC_SIMULATOR_PROMPT = `
-# TON RÔLE
-Tu dois vérifier le comportement d'un AGENT CONVERSATIONNEL externe (The Guardian).
-TU AS DEUX PERSONNALITÉS SIMULTANÉES: LE SIMULATEUR D'UN UTILISATEUR HUMAIN ET L'OBSERVATEUR DE LA CONVERSATION.
-Chacune de tes réponses est une question posée à l'agent testé.
-Comporte-toi naturellement selon la personnalité spécifiée plus bas.
+function GENERIC_SIMULATOR_PROMPT(scenario, instructionEx) {
+    const persona = scenario.persona || scenario.testPersona || '';
+    const goals = scenario.goals || scenario.testGoals || '';
+    const resultFormat = scenario.result || scenario.testResult || '';
+    return `# IDENTITÉ
+Tu es un **TESTEUR AUTOMATISÉ** conçu pour évaluer un **AGENT CONVERSATIONNEL** externe selon le **Mirror Agent Model** :  
+* Un schéma où un agent simulé interagit en miroir avec un agent observé, pendant qu'un observateur caché vérifie la conformité aux objectifs \`<simulation_goals>\`.
+
+Tu incarnes **deux rôles distincts et simultanés** :
+1. **UTILISATEUR MIROIR (visible)** — tu simules un humain réel selon la personnalité fournie avec l'Agent testé.  
+2. **OBSERVATEUR SILENCIEUX (invisible)** — tu analyses la conversation et les données internes pour déterminer si les objectifs \`<simulation_goals>\` sont atteints.
+
+# MISSION
+- Tu reçois un message en entrée provenant de l'Agent testé (nommé "l'Agent").
+- Tu l'analyses en tant qu'<identity_observer>. Tu peux décider de terminer la simulation. 
+- Puis tu réponds en tant qu'<identity_user>. (nommé "Toi")
+---
+
+<identity_user>
+## RÔLE 1 (Utilisateur) — UTILISATEUR MIROIR (visible)
+- Tu représentes un **utilisateur humain typique** qui bluf l'Agent testé selon la **Personnalité** fournie.  
+- Tu t'exprimes en **langage naturel**, sans jargon ni répétition.  
+- Tu **ignores** tout du fonctionnement interne de l'Agent testé et de ses outils.  
+- Tu **ne mentionnes jamais** des éléments de tes identités <identity_observer> et <identity_user> et de ta mission.
+- Tu ne répète jamais la réponse de l'agent observé.
 
-## PERSONNALITÉ 1 - LE SIMULATEUR DU CLIENT (visible par l'agent )
-Tu es le simulateur d'un utilisateur normal qui pose des questions à un agent. 
-Dans ce contexte, chacune de tes réponses est une question pour l'agent externe, et chacune de ses réponses est la prochaine question pour toi.
-- Tu parles UNIQUEMENT en texte naturel non répétitif.
-- Tu ne connais RIEN sur le fonctionnement technique de l'agent
-- Tu ne mentionnes JAMAIS: "Objectifs", "Conditions", "Validation", "Transfert", "Outil", "Simulation"
-- Tu te comportes selon la **Personnalité** fournie
-Tu reçois les conditions initiales suivantes qui décrivent l'objectif de la simulation:
-- **Personnalité**: caractère du CLIENT
-- **Question**: la première question à poser à l'agent externe (sans interprétation, juste la question brute).
+- Voici la personnalité de l'utilisateur simulé:
+${persona}
 
+Exemple de conversation:
+> Agent : "Souhaitez-vous tout le canton ou une zone précise ?"  
+> Toi : "Tout le canton de Genève." ✅
+</identity_user>
 
-## PERSONNALITÉ 2 - L'OBSERVATEUR (secret, invisible)
-En parallèle, tu observes secrètement si l'agent répond correctement.
-- Tu notes mentalement si les **Objectifs** sont atteints ou partiellement atteints (incrémentale).
-- Tu ne RÉVÈLES JAMAIS les observations dans tes messages.
-- Quand les Objectifs sont atteints → tu produis \`[DONE] {JSON}\`
+---
 
+<identity_observer>
+## RÔLE 2 — OBSERVATEUR SILENCIEUX (invisible)
+- Tu observes toutes les questions de l'Agent testé et détermine l'arrêt de la simulation selon les **Objectifs** du \`<simulation_goals>\` 
+- Tu utilises également, si présent, (\`<agent-context>\`) pour déterminer l'arrêt de la simulation.
+- Tu es silencieux et ne réponds jamais rien à l'exception du trigger de fin:
+  Tu retournes le trigger de fin: \`[DONE] {"success": true, "explain": "..."}\` ou \`[DONE] {"success": false, "error": "..."}\`.
 
-Tu reçois les conditions initiales suivantes qui décrivent l'objectif de l'observation':
-- **Objectifs**: ce que l'OBSERVATEUR doit vérifier de la discussion avec l'agent (Attention c'est interne)
-  ⚠️ jamais mentionné cette analyse interne, mais elle guide le comportement de la "PERSONNALITÉ 1"  pour atteindre les objectifs.
-- **Format JSON**: structure du rapport de l'OBSERVATEUR
+### CONTEXT (\`<agent-context>\` invisible pour le CLIENT)
+- Le tag \`<agent-context>\` contient des données techniques de l'agent testé (outils appelés, nombre d'échanges, etc).  
+- Ces informations sont **strictement réservées à toi l'observateur.  
+**AUTORISÉ** : les exploiter pour valider les objectifs ou décider de la fin du test.  
 
+Exemple avec sortie pour <simulation_goals>CONDITION DE FIN: L'agent demande si l'utilisateur souhaite chercher sur internet</simulation_goals>:
+> Toi : "Quelle est la température du lac à Genève ?"  
+> Agent : "Je n'ai pas cette information, souhaitez-vous que je cherche sur internet ?"  
+> Toi : "[DONE] {success=true, ...}" ✅
 
-# FLUX DE CONVERSATION
-1. Reçois l'INPUT avec ta **Question** initiale
-2. Pose cette question à l'agent (PERSONNALITÉ CLIENT)
-3. L'agent répond
-4. Observe si les **Objectifs** sont atteints (PERSONNALITÉ OBSERVATEUR)
-5. Choisis ta sortie:
-   - Objectifs partiellement atteints → continue la conversation pour atteindre les objectifs complets.
-   - Objectifs atteints → \`[DONE] {"success": true}\`
-   - Comportement interdit → \`[DONE] {"success": false, "error": "..."}\` explique la raison de l'échec.
+</identity_observer>
+---
 
-# QUAND PRODUIRE [DONE]
-L'OBSERVATEUR décide de terminer, mais le CLIENT ne le sait pas.
-Le CLIENT continue à parler naturellement jusqu'à ce que l'OBSERVATEUR émette [DONE].
+# PLAN DE SIMULATION
+<simulation_goals>
+${goals}
+</simulation_goals>
 
-# FORMAT INPUT
-- **Personnalité**: caractère du CLIENT
-- **Question**: ce que le CLIENT demande initialement
-- **Objectifs**: ce que l'OBSERVATEUR doit vérifier (PRIVÉ, jamais mentionné par le CLIENT)
-- **Format JSON**: format du rapport de l'OBSERVATEUR
+<simulation_result_format>
+${resultFormat}
+</simulation_result_format>
 
-`;
+**CRITICAL**: Your response after [DONE] must be valid JSON format only.
+${instructionEx ? `\n\n${instructionEx}` : ''}`;
+}
 /**
  * 3 prompts variables de personnalité pré-définis à choisir manuellement
  */
 exports.PERSONA_PATIENT = 'Utilisateur patient et poli qui prend le temps d\'expliquer sa situation';
 exports.PERSONA_PRESSE = 'Utilisateur pressé qui veut une solution rapide, répond brièvement';
 exports.PERSONA_ENERVE = 'Utilisateur énervé et frustré, c\'est son 3ème appel pour le même problème, ton direct et impatient';
-/**
- * Construire la query formatée selon le format SimulationScenario
- * Supporte l'ancien format avec testQuery pour rétrocompatibilité
- */
-const buildSimulatorQuery = (scenario, query) => {
-    // Extraire query depuis les paramètres ou depuis scenario.testQuery (ancien format)
-    const actualQuery = query || scenario.testQuery || '';
-    const persona = scenario.persona || scenario.testPersona || '';
-    const goals = scenario.goals || scenario.testGoals || '';
-    const result = scenario.result || scenario.testResult || '';
-    return `- **Personnalité**: ${persona}
-- **Question**: ${actualQuery}
-- **Objectifs**: ${goals}
-- **Format JSON**: ${result}`;
-};
-exports.buildSimulatorQuery = buildSimulatorQuery;

package/dist/src/agents/simulator.types.d.ts

@@ -9,6 +9,38 @@ export interface SimulatorConfig {
     mockCacheInitializer?: (sessionId: string) => Promise<void>;
     ragConfig?: RAGManagerConfig;
 }
+/**
+ * Scénario de test - Contexte stable entre les tests
+ * Définit la personnalité du simulateur et les objectifs de validation
+ */
+export interface TestScenario {
+    description?: string;
+    goals: string;
+    persona: string;
+    result?: string;
+}
+/**
+ * Contrainte de validation pour un outil
+ */
+export interface ToolConstraint {
+    equal?: number;
+    gte?: number;
+    lte?: number;
+}
+/**
+ * Cas de test spécifique - Varie pour chaque test
+ * Définit la query et les attentes de validation
+ */
+export interface TestCaseInput {
+    query: string;
+    maxExchanges?: number;
+    model?: string;
+    expectedTools?: Record<string, ToolConstraint>;
+    onMessage?: (message: AgentMessage) => void;
+}
+/**
+ * @deprecated Utiliser TestScenario à la place
+ */
 export interface SimulationScenario {
     goals?: string;
     persona?: string;
@@ -20,13 +52,14 @@ export interface SimulationScenario {
     testQuery?: string;
     testResult?: string;
 }
+/**
+ * @deprecated Utiliser testCase(scenario, case) à la place de executeSimulation(options)
+ */
 export interface SimulationOptions {
     scenario: SimulationScenario;
     query?: string;
     maxExchanges: number;
-    expectedTool?: Record<string, {
-        equal: number;
-    }>;
+    expectedTool?: Record<string, ToolConstraint>;
     onMessage?: (message: AgentMessage) => void;
 }
 export interface SimulationResult {
@@ -44,11 +77,13 @@ export interface SimulationResult {
 export interface ExecutionContext {
     agentContext: AgenticContext;
     simulatorContext: AgenticContext;
+    simulatorAgent: AgentConfig;
     conversationHistory: string[];
     exchangeCount: number;
     lastExecution: ExecutionResult;
 }
-export interface TestScenario {
+/** @deprecated Utiliser TestScenario avec l'API testCase() */
+export interface PRSolverScenario {
     ticketId: string;
     ticketMarkdown: string;
     clientType: 'locataire' | 'proprietaire';

package/dist/src/agents/simulator.utils.d.ts

@@ -1,4 +1,4 @@
-import { SimulationScenario } from './simulator.types';
+import { SimulationScenario, TestScenario } from './simulator.types';
 import { PERSONA_PATIENT, PERSONA_PRESSE, PERSONA_ENERVE } from './simulator.prompts';
 /**
  * Charger un ticket depuis le filesystem (comme agent-vs-agent.ts)
@@ -22,4 +22,25 @@ custom?: Partial<SimulationScenario>): {
  * Supporte l'ancien format (testGoals, testEnd, etc.) pour rétrocompatibilité
  */
 export declare function buildGenericScenario(scenario: SimulationScenario): SimulationScenario;
+/**
+ * Créer un TestScenario pour la nouvelle API testCase()
+ *
+ * @example
+ * ```typescript
+ * const scenario = createTestScenario({
+ *   goals: 'Obtenir le nombre secret 1942',
+ *   persona: PERSONA_PATIENT
+ * });
+ *
+ * const result = await simulator.testCase(scenario, {
+ *   query: 'À quel nombre penses-tu?'
+ * });
+ * ```
+ */
+export declare function createTestScenario(options: {
+    description?: string;
+    goals: string;
+    persona: string;
+    result?: string;
+}): TestScenario;
 export { PERSONA_PATIENT, PERSONA_PRESSE, PERSONA_ENERVE };

package/dist/src/agents/simulator.utils.js

@@ -37,6 +37,7 @@ exports.PERSONA_ENERVE = exports.PERSONA_PRESSE = exports.PERSONA_PATIENT = void
 exports.loadScenario = loadScenario;
 exports.buildScenarioFromTicket = buildScenarioFromTicket;
 exports.buildGenericScenario = buildGenericScenario;
+exports.createTestScenario = createTestScenario;
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const simulator_prompts_1 = require("./simulator.prompts");
@@ -97,8 +98,6 @@ function buildGenericScenario(scenario) {
             goals: goals.trim(),
             persona: scenario.testPersona || scenario.persona || '',
             result: scenario.testResult || scenario.result || '{"success": boolean, "error": string, "description": string}',
-            // Garder testQuery pour extraction ultérieure
-            testQuery: scenario.testQuery
         };
     }
     // Nouveau format - juste ajouter un result par défaut si manquant
@@ -107,3 +106,29 @@ function buildGenericScenario(scenario) {
         result: scenario.result || '{"success": boolean, "error": string, "description": string}'
     };
 }
+// ============================================================================
+// NOUVELLE API : createTestScenario (pour testCase)
+// ============================================================================
+/**
+ * Créer un TestScenario pour la nouvelle API testCase()
+ *
+ * @example
+ * ```typescript
+ * const scenario = createTestScenario({
+ *   goals: 'Obtenir le nombre secret 1942',
+ *   persona: PERSONA_PATIENT
+ * });
+ *
+ * const result = await simulator.testCase(scenario, {
+ *   query: 'À quel nombre penses-tu?'
+ * });
+ * ```
+ */
+function createTestScenario(options) {
+    return {
+        description: options.description,
+        goals: options.goals,
+        persona: options.persona,
+        result: options.result || '{"success": boolean, "explain": string, "error": string}'
+    };
+}

package/dist/src/execute/helpers.d.ts

@@ -0,0 +1,75 @@
+import { AgentStateGraph } from '../stategraph';
+import { AgentConfig, AgenticContext, ExecutionAction } from '../types';
+/**
+ * OPTIM: Accumule l'usage des tokens et met à jour stateGraph + discussion.usage
+ *
+ * Centralise la logique d'accumulation des tokens qui était dupliquée
+ * à plusieurs endroits dans le code original
+ *
+ * @param stateGraph - Instance du StateGraph
+ * @param discussion - Discussion courante
+ * @param agentName - Nom de l'agent (discussionRootAgent)
+ * @param model - Nom du modèle (pour calcul du coût)
+ * @param usage - Usage retourné par l'API (prompt_tokens, completion_tokens, total_tokens)
+ */
+export declare function accumulateUsageTokens(stateGraph: AgentStateGraph, discussion: any, agentName: string, model: string, usage: any): void;
+/**
+ * OPTIM: Convertit les steps du stateGraph en actions ExecutionResult
+ *
+ * Centralise la logique de conversion qui était dupliquée
+ * à plusieurs endroits dans le code original
+ *
+ * TODO/FIXME [Phase 3 - Normalisation]: Normaliser l'interface ExecutionAction
+ * Actuellement on fait un mapping manuel (tool→action, context→content, reason→feedback)
+ * À terme, utiliser directement le type StepTrail (tool, context, reason) partout
+ * au lieu d'ExecutionAction (action, content, feedback).
+ * Cela simplifiera le code et évitera les conversions répétées.
+ *
+ * @param stateGraph - Instance du StateGraph
+ * @param agentName - Nom de l'agent (discussionRootAgent)
+ * @returns Array d'actions pour ExecutionResult
+ */
+export declare function stepsToActions(stateGraph: AgentStateGraph, agentName: string): ExecutionAction[];
+/**
+ * OPTIM: Traite tous les tool calls en batch et retourne les résultats
+ *
+ * Exploite parallel_tool_calls pour optimiser les follow-ups :
+ * - Parse tous les arguments JSON une seule fois
+ * - Traite tous les tool calls
+ * - Accumule les messages pour un seul follow-up stream
+ *
+ * Au lieu de :
+ *   for (toolCall) {
+ *     handleTransferCall(toolCall)
+ *     followUpStream()  // ← Un stream par tool call (séquentiel)
+ *   }
+ *
+ * On fait :
+ *   batchProcessToolCalls(allToolCalls)
+ *   followUpStream()  // ← Un seul stream pour tous les résultats (batch)
+ *
+ * ✅ NEW: Support de submitToolOutputs (Responses API)
+ * Si responseId et openai sont fournis, utilise submitToolOutputs pour
+ * soumettre les résultats directement à l'API au lieu de les accumuler
+ * dans le stateGraph. Sinon, utilise l'approche classique (fallback).
+ *
+ * @param toolCalls - Array de tool calls retournés par l'API
+ * @param agents - Liste de tous les agents
+ * @param stateGraph - Instance du StateGraph
+ * @param agentName - Nom de l'agent (discussionRootAgent)
+ * @param context - Context (AgenticContext, doit contenir discussionRootAgent, currentAgent et stateGraph)
+ * @param responseId - (Optional) Response ID pour submitToolOutputs (Responses API)
+ * @param verbose - (Optional) Mode verbose pour logs
+ * @returns Résultats de tous les tool calls + flag needsFollowUp + parsedCalls (avec args parsés)
+ */
+export declare function batchProcessToolCalls(toolCalls: any[], agents: AgentConfig[], stateGraph: AgentStateGraph, agentName: string, context: AgenticContext, responseId?: string, verbose?: boolean): Promise<{
+    results: any[];
+    needsFollowUp: boolean;
+    parsedCalls: any[];
+    transferAgentName: string;
+    hasTransfer: boolean;
+    toolOutputs: Array<{
+        call_id: string;
+        output: string;
+    }>;
+}>;

package/dist/src/execute/helpers.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.accumulateUsageTokens = accumulateUsageTokens;
+exports.stepsToActions = stepsToActions;
+exports.batchProcessToolCalls = batchProcessToolCalls;
+const pricing_1 = require("../llm/pricing");
+const utils_1 = require("../utils");
+/**
+ * OPTIM: Accumule l'usage des tokens et met à jour stateGraph + discussion.usage
+ *
+ * Centralise la logique d'accumulation des tokens qui était dupliquée
+ * à plusieurs endroits dans le code original
+ *
+ * @param stateGraph - Instance du StateGraph
+ * @param discussion - Discussion courante
+ * @param agentName - Nom de l'agent (discussionRootAgent)
+ * @param model - Nom du modèle (pour calcul du coût)
+ * @param usage - Usage retourné par l'API (prompt_tokens, completion_tokens, total_tokens)
+ */
+function accumulateUsageTokens(stateGraph, discussion, agentName, model, usage) {
+    (0, pricing_1.accumulateCost)(discussion.usage, model, usage);
+    stateGraph.updateTokens(agentName, {
+        prompt: usage?.prompt_tokens || 0,
+        completion: usage?.completion_tokens || 0,
+        total: usage?.total_tokens || 0,
+        cost: 0 // Already accumulated in discussion.usage
+    });
+}
+/**
+ * OPTIM: Convertit les steps du stateGraph en actions ExecutionResult
+ *
+ * Centralise la logique de conversion qui était dupliquée
+ * à plusieurs endroits dans le code original
+ *
+ * TODO/FIXME [Phase 3 - Normalisation]: Normaliser l'interface ExecutionAction
+ * Actuellement on fait un mapping manuel (tool→action, context→content, reason→feedback)
+ * À terme, utiliser directement le type StepTrail (tool, context, reason) partout
+ * au lieu d'ExecutionAction (action, content, feedback).
+ * Cela simplifiera le code et évitera les conversions répétées.
+ *
+ * @param stateGraph - Instance du StateGraph
+ * @param agentName - Nom de l'agent (discussionRootAgent)
+ * @returns Array d'actions pour ExecutionResult
+ */
+function stepsToActions(stateGraph, agentName) {
+    return stateGraph.steps(agentName).map(step => ({
+        action: step.tool,
+        content: step.context,
+        feedback: step.reason
+    }));
+}
+/**
+ * OPTIM: Traite tous les tool calls en batch et retourne les résultats
+ *
+ * Exploite parallel_tool_calls pour optimiser les follow-ups :
+ * - Parse tous les arguments JSON une seule fois
+ * - Traite tous les tool calls
+ * - Accumule les messages pour un seul follow-up stream
+ *
+ * Au lieu de :
+ *   for (toolCall) {
+ *     handleTransferCall(toolCall)
+ *     followUpStream()  // ← Un stream par tool call (séquentiel)
+ *   }
+ *
+ * On fait :
+ *   batchProcessToolCalls(allToolCalls)
+ *   followUpStream()  // ← Un seul stream pour tous les résultats (batch)
+ *
+ * ✅ NEW: Support de submitToolOutputs (Responses API)
+ * Si responseId et openai sont fournis, utilise submitToolOutputs pour
+ * soumettre les résultats directement à l'API au lieu de les accumuler
+ * dans le stateGraph. Sinon, utilise l'approche classique (fallback).
+ *
+ * @param toolCalls - Array de tool calls retournés par l'API
+ * @param agents - Liste de tous les agents
+ * @param stateGraph - Instance du StateGraph
+ * @param agentName - Nom de l'agent (discussionRootAgent)
+ * @param context - Context (AgenticContext, doit contenir discussionRootAgent, currentAgent et stateGraph)
+ * @param responseId - (Optional) Response ID pour submitToolOutputs (Responses API)
+ * @param verbose - (Optional) Mode verbose pour logs
+ * @returns Résultats de tous les tool calls + flag needsFollowUp + parsedCalls (avec args parsés)
+ */
+async function batchProcessToolCalls(toolCalls, agents, stateGraph, agentName, context, responseId, verbose) {
+    const results = [];
+    let needsFollowUp = false;
+    let transferAgentName = '';
+    let hasTransfer = false; // ✅ Flag pour détecter les transfers
+    //
+    // ✅ Récupérer discussion depuis stateGraph
+    const discussion = stateGraph.createOrRestore(agentName);
+    //
+    // ✅ Créer currentAgentRef depuis agentName (référence mutable pour handleTransferCall)
+    const currentAgentRef = { name: agentName };
+    //
+    // OPTIM: Parse tous les args une seule fois
+    const parsedCalls = toolCalls.map(tc => ({
+        ...tc,
+        args: JSON.parse(tc?.function?.arguments || '{}')
+    }));
+    //
+    // ✅ Préparer les tool_outputs pour submitToolOutputs
+    const toolOutputs = [];
+    //
+    // Traiter tous les tool calls
+    for (const toolCall of parsedCalls) {
+        const result = await (0, utils_1.handleTransferCall)(discussion, currentAgentRef, agents, toolCall, context);
+        results.push(result);
+        // ✅ Détecter les transfers
+        if (result.did_transfer && result.destination_agent) {
+            hasTransfer = true;
+            transferAgentName = result.destination_agent;
+        }
+        //
+        // Accumuler les messages pour le follow-up
+        // ✅ IMPORTANT: Toujours ajouter l'output même si content est undefined
+        // Car un ToolContractOutput peut ne pas avoir de content mais avoir rawResult
+        if (result.content || result.did_transfer || result.rawResult) {
+            needsFollowUp = true;
+            // ✅ Préparer les outputs pour function_call_output
+            // Si content existe, l'utiliser (texte formaté)
+            // Sinon, sérialiser rawResult si présent (ToolContractOutput), sinon result complet
+            toolOutputs.push({
+                call_id: toolCall.id,
+                // ⚠️ ATTENTION: rawResult contient le résultat brut du tool (ToolContractOutput)
+                // Si content est undefined, on sérialise rawResult pour préserver la structure JSON complète
+                // Sinon, on utilise result complet comme fallback
+                output: result.content || JSON.stringify(result.rawResult || result)
+            });
+        }
+        //
+        // ✅ Les steps sont ajoutés APRÈS le follow-up dans readCompletionsStream
+        // pour éviter que le LLM pense que l'outil a déjà été exécuté
+    }
+    // ✅ NOTE: On ne gère PAS submitToolOutputs ici
+    // C'est readCompletionsStream qui décide selon hasTransfer
+    // On retourne juste les données nécessaires
+    return { results, needsFollowUp, parsedCalls, transferAgentName, hasTransfer, toolOutputs };
+}

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

@@ -0,0 +1,11 @@
+/**
+ * @fileoverview Point d'entrée du module execute avec feature toggle
+ *
+ * Feature toggle : basculer entre Chat Completions (legacy) et Responses API
+ * Contrôlé par la variable d'environnement USE_RESPONSES_API
+ */
+export declare const USE_RESPONSES_API: boolean;
+export * from './shared';
+export * from './helpers';
+export * from './modelconfig';
+export * from './responses';

package/dist/src/execute/index.js

@@ -0,0 +1,44 @@
+"use strict";
+/**
+ * @fileoverview Point d'entrée du module execute avec feature toggle
+ *
+ * Feature toggle : basculer entre Chat Completions (legacy) et Responses API
+ * Contrôlé par la variable d'environnement USE_RESPONSES_API
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.USE_RESPONSES_API = void 0;
+//
+// Feature toggle: basculer entre legacy et responses
+// Par défaut : Responses API (meilleur support reasoning models)
+// Pour revenir à legacy : USE_RESPONSES_API=false
+exports.USE_RESPONSES_API = process.env.USE_RESPONSES_API !== 'false';
+//
+// Exports des utilitaires partagés
+__exportStar(require("./shared"), exports);
+__exportStar(require("./helpers"), exports);
+__exportStar(require("./modelconfig"), exports);
+//
+// Exports conditionnels selon le feature flag
+// Par défaut : responses.ts (Responses API)
+// Si USE_RESPONSES_API=false → legacy.ts (Chat Completions)
+// const implementation = USE_RESPONSES_API 
+//   ? require('./responses')
+//   : require('./legacy');
+__exportStar(require("./responses"), exports);
+// export const executeQuery = implementation.executeQuery;
+// export const executeAgent = implementation.executeAgent;
+// export const executeAgentSet = implementation.executeAgentSet;

package/dist/src/execute/legacy.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Legacy Implementation - Chat Completions API (beta.chat.completions)
+ *
+ * ⚠️ Cette implémentation utilise openai.beta.chat.completions.stream (ancienne API)
+ * Pour les nouveaux projets, Responses API (responses.ts) est recommandée.
+ *
+ * Code optimisé depuis execute.ts original avec les améliorations suivantes:
+ * - OPTIM: Helpers centralisés (accumulateUsageTokens, stepsToActions)
+ * - BUG FIX: executionResultMerge fusionne actions correctement (corrigé dans types.ts)
+ * - BUG FIX: moreThinkin supprimé (obsolète, reasoning_effort fait le job)
+ * - BUG FIX: Suppression de la boucle do...while(moreThinkin)
+ * - BUG FIX: Suppression de la ligne reasoning_effort dupliquée (ligne 425 originale)
+ *
+ * TODO [Optimisation future]: Remplacer la boucle for séquentielle par batchProcessToolCalls
+ * pour exploiter pleinement parallel_tool_calls et réduire la latence
+ */
+import { AgentConfig, AgenticContext, ExecuteAgentResult, ExecutionResult } from "../types";
+import { ReadCompletionsStreamOptions, ExecuteAgentSetParams } from "./shared";
+export declare function readCompletionsStream(params: ReadCompletionsStreamOptions): Promise<ExecutionResult>;
+/**
+ * Parameters for executing an agent set
+ */
+export interface ExecuteAgentSetParamsLegacy {
+    enrichWithMemory?: (role: string, agent: AgentConfig, context: AgenticContext) => Promise<string>;
+    query: string;
+    home?: string;
+    thinking?: boolean;
+    model?: string;
+    stdout: any;
+    messages?: any[];
+    verbose?: boolean;
+    json?: boolean;
+    schema?: any;
+    debug?: boolean;
+}
+/**
+ * Executes a set of agents to process a user query
+ *
+ * OPTIMIZED: Sans boucle do...while(moreThinkin), reasoning_effort fait le job
+ */
+export declare function executeAgentSet(agentSet: AgentConfig[], context: AgenticContext, params: ExecuteAgentSetParams): Promise<ExecutionResult>;
+export declare function executeAgent(agentSet: AgentConfig[], params: ExecuteAgentSetParams): Promise<ExecuteAgentResult>;
+/**
+ * Executes a simple query without agent orchestration or tool handling
+ */
+export declare function executeQuery(params: ExecuteAgentSetParams): Promise<ExecuteAgentResult>;