agentic-api 2.0.646 → 2.0.885

package/dist/src/agents/subagent.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * SubAgent — Injection et introspection des sub-agents
+ *
+ * Toutes les fonctions liées au pattern subAgent<Name> :
+ * - subAgentInjectTools()          : génère les tools subAgent<Name> pour le parent
+ * - subAgentExtractCapabilities()  : résumé des capacités (1ère ligne de chaque tool description)
+ * - SUBAGENT_TOOL_PARAMS           : schéma paramètres par défaut (query, context, goal)
+ *
+ * Séparation parent-facing vs subAgent-facing :
+ * - Parent-facing  : publicDescription + capabilities + params schema (vu par le parent LLM)
+ * - SubAgent-facing : instructions internes (graph, routage, contrat — défini côté serveur)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SUBAGENT_OUTPUT_SCHEMA = exports.SUBAGENT_REQUIRED_PARAMS = exports.SUBAGENT_TOOL_PARAMS = void 0;
+exports.parseSubAgentOutputContent = parseSubAgentOutputContent;
+exports.subAgentExtractCapabilities = subAgentExtractCapabilities;
+exports.subAgentComposeMission = subAgentComposeMission;
+exports.subAgentInjectTools = subAgentInjectTools;
+// ============================================================================
+// SUBAGENT_TOOL_PARAMS — schéma par défaut (query, context, goal)
+// ============================================================================
+/**
+ * Paramètres par défaut du tool subAgent<Name>.
+ * Descriptions génériques et courtes (best practice OpenAI).
+ * Les exemples domaine sont dans publicDescription de chaque subAgent.
+ */
+exports.SUBAGENT_TOOL_PARAMS = {
+    query: {
+        type: 'string',
+        description: 'Question utilisateur ou intention normalisée.',
+    },
+    context: {
+        type: 'string',
+        description: 'Entités pré-résolues par le parent (nom, entité, IDs). Vide si rien pré-résolu.',
+    },
+    goal: {
+        type: 'string',
+        description: 'Livrable attendu — condition d\'arrêt du sub-agent.',
+    },
+};
+exports.SUBAGENT_REQUIRED_PARAMS = ['query', 'context', 'goal'];
+/**
+ * Schéma de sortie générique des sous-agents.
+ * Les `items` sont sérialisés en chaînes JSON pour rester compatibles avec
+ * le mode `json_schema strict` tout en conservant une structure métier libre.
+ */
+exports.SUBAGENT_OUTPUT_SCHEMA = {
+    type: 'object',
+    additionalProperties: false,
+    required: ['status', 'items', 'meta', 'control'],
+    properties: {
+        status: {
+            type: 'string',
+            enum: ['ok', 'empty', 'error']
+        },
+        items: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        },
+        meta: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['resolved', 'notFound', 'knowledge_found'],
+            properties: {
+                resolved: {
+                    type: 'array',
+                    items: { type: 'string' }
+                },
+                notFound: {
+                    type: 'array',
+                    items: { type: 'string' }
+                },
+                knowledge_found: {
+                    type: 'string',
+                    enum: ['no', 'yes', 'partial', 'conflict']
+                }
+            }
+        },
+        control: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['can_retry'],
+            properties: {
+                can_retry: { type: 'boolean' }
+            }
+        }
+    }
+};
+function parseSubAgentOutputContent(content) {
+    try {
+        const parsed = JSON.parse(content);
+        if (!parsed || typeof parsed !== 'object') {
+            return null;
+        }
+        if (!['ok', 'empty', 'error'].includes(parsed.status)) {
+            return null;
+        }
+        if (!Array.isArray(parsed.items) || !parsed.items.every((item) => typeof item === 'string')) {
+            return null;
+        }
+        const meta = parsed.meta;
+        if (!meta
+            || !Array.isArray(meta.resolved)
+            || !meta.resolved.every((value) => typeof value === 'string')
+            || !Array.isArray(meta.notFound)
+            || !meta.notFound.every((value) => typeof value === 'string')
+            || !['no', 'yes', 'partial', 'conflict'].includes(meta.knowledge_found)) {
+            return null;
+        }
+        const control = parsed.control;
+        if (!control || typeof control.can_retry !== 'boolean') {
+            return null;
+        }
+        return {
+            status: parsed.status,
+            items: parsed.items,
+            meta: {
+                resolved: meta.resolved,
+                notFound: meta.notFound,
+                knowledge_found: meta.knowledge_found
+            },
+            control: {
+                can_retry: control.can_retry
+            }
+        };
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================================
+// subAgentExtractCapabilities — parent-facing
+// ============================================================================
+/**
+ * Extrait les capacités d'un agent depuis ses tools.
+ * Prend la 1ère ligne de chaque `function.description`.
+ */
+function subAgentExtractCapabilities(agents, name) {
+    const agent = agents.find(a => a.name === name) ?? agents[0];
+    if (!agent?.tools?.length)
+        return '';
+    return agent.tools
+        .filter(t => t.function?.name && t.function?.description)
+        .map(t => {
+        const fn = t.function;
+        const firstLine = fn.description.trim().split('\n')[0];
+        return `- ${fn.name}: ${firstLine}`;
+    })
+        .join('\n');
+}
+// ============================================================================
+// subAgentComposeMission — convertit les args du tool en mission texte
+// ============================================================================
+/**
+ * Compose la mission envoyée au sub-agent depuis les arguments du tool.
+ * Supporte les deux formats (ancien triplet et nouveau query/context/goal).
+ */
+function subAgentComposeMission(args) {
+    //
+    // Nouveau format (query, context, goal)
+    if (args.query != null || args.goal != null) {
+        const parts = [];
+        if (args.query)
+            parts.push(`## Question\n${args.query}`);
+        if (args.context)
+            parts.push(`## Contexte\n${args.context}`);
+        if (args.goal)
+            parts.push(`## Livrable\n${args.goal}`);
+        return parts.join('\n\n');
+    }
+    //
+    // Ancien format (subject, context, expected_result) — rétro-compatibilité
+    const { subject, context, expected_result } = args;
+    return `## Sujet\n${subject}\n\n## Contexte\n${context}\n\n## Résultat attendu\n${expected_result}`;
+}
+// ============================================================================
+// subAgentInjectTools — parent-facing
+// ============================================================================
+/**
+ * Injecte un tool `subAgent<Name>` par sub-agent déclaré dans `agentDef.subAgents`.
+ *
+ * Le schéma des paramètres provient de :
+ * 1. `subAgent.subAgentToolParams` (override spécifique)
+ * 2. `SUBAGENT_TOOL_PARAMS` (défaut: query, context, goal)
+ */
+function subAgentInjectTools(agentDefs) {
+    const subAgentRegistry = [];
+    const processedAgents = agentDefs.map(agentDef => {
+        const subAgents = (agentDef.subAgents ?? []);
+        if (subAgents.length === 0)
+            return agentDef;
+        const tools = agentDef.tools ? [...agentDef.tools] : [];
+        subAgents.forEach(subAgent => {
+            const toolName = `subAgent${subAgent.name.charAt(0).toUpperCase()}${subAgent.name.slice(1)}`;
+            if (tools.find(t => t.function.name === toolName)) {
+                return;
+            }
+            const capabilities = subAgentExtractCapabilities([subAgent], subAgent.name);
+            const subAgentTool = {
+                type: 'function',
+                function: {
+                    name: toolName,
+                    description: `Délègue une mission au sub-agent ${subAgent.name}.
+${subAgent.publicDescription ?? ''}
+${capabilities ? `\nCapacités :\n${capabilities}` : ''}
+Le sub-agent s'arrête dès que le goal est satisfait.`,
+                    parameters: {
+                        type: 'object',
+                        properties: { ...exports.SUBAGENT_TOOL_PARAMS },
+                        required: exports.SUBAGENT_REQUIRED_PARAMS,
+                        additionalProperties: false
+                    },
+                    strict: true
+                }
+            };
+            tools.push(subAgentTool);
+            if (subAgent.instructions && !subAgentRegistry.find(x => x.name === subAgent.name)) {
+                subAgentRegistry.push(subAgent);
+            }
+        });
+        return {
+            ...agentDef,
+            tools,
+            subAgents: subAgents.map(({ name, publicDescription }) => ({ name, publicDescription }))
+        };
+    });
+    return [...processedAgents, ...subAgentRegistry];
+}

package/dist/src/agents/worker.executor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * @fileoverview Pont WorkerJob → AgentSimulator(mode: worker) → ToolContractOutput
+ *
+ * Utilise l'infrastructure existante du simulateur adaptée en mode worker.
+ * Le contrat de retour suit ToolContractOutput<WorkerOutputV1>.
+ */
+import { WorkerJob } from './reducer.loaders';
+import { JobEvent } from './job.runner';
+import { AgenticContext, ToolContractOutput } from '../types';
+/**
+ * Données du deliverable Worker — le T de ToolContractOutput<T>
+ */
+export interface WorkerDeliverable {
+    /** Le résultat complet de la mission */
+    deliverable: string;
+    /** Résumé court de ce qui a été accompli */
+    summary: string;
+    /** Temps total en ms */
+    duration: number;
+    /** Contrat JSON natif minimal pour intégrations API/UI */
+    result: WorkerOutputV1;
+}
+/**
+ * Contrat JSON natif minimal du Worker.
+ */
+export interface WorkerOutputV1 {
+    version: 'worker_output_v1';
+    status: 'completed' | 'partial' | 'failed';
+    summary: string;
+    deliverable: string;
+    runId: string;
+    error?: string;
+}
+/**
+ * Exécute un WorkerJob via AgentSimulator en mode worker
+ *
+ * Callable depuis : Discussion (tool), Cron, Job, API
+ * Retourne ToolContractOutput<WorkerOutputV1>
+ *
+ * @param workerJob - WorkerJob avec positionDescription + agent + maxIterations
+ * @param query - La demande/question de job (premier message envoyé à l'Agent)
+ * @param agentContext - Contexte réel (RAG, session, credentials — déjà initialisé)
+ * @param options - Options additionnelles
+ */
+export declare function executeWorkerJob(workerJob: WorkerJob, query: string, agentContext: AgenticContext, options?: {
+    extend?: boolean;
+    onEvent?: (event: JobEvent) => void;
+}): Promise<ToolContractOutput<WorkerOutputV1>>;

package/dist/src/agents/worker.executor.js

@@ -0,0 +1,152 @@
+"use strict";
+/**
+ * @fileoverview Pont WorkerJob → AgentSimulator(mode: worker) → ToolContractOutput
+ *
+ * Utilise l'infrastructure existante du simulateur adaptée en mode worker.
+ * Le contrat de retour suit ToolContractOutput<WorkerOutputV1>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeWorkerJob = executeWorkerJob;
+const simulator_1 = require("./simulator");
+// ============================================================================
+// Exécution standalone — multi-source
+// ============================================================================
+/**
+ * Exécute un WorkerJob via AgentSimulator en mode worker
+ *
+ * Callable depuis : Discussion (tool), Cron, Job, API
+ * Retourne ToolContractOutput<WorkerOutputV1>
+ *
+ * @param workerJob - WorkerJob avec positionDescription + agent + maxIterations
+ * @param query - La demande/question de job (premier message envoyé à l'Agent)
+ * @param agentContext - Contexte réel (RAG, session, credentials — déjà initialisé)
+ * @param options - Options additionnelles
+ */
+async function executeWorkerJob(workerJob, query, agentContext, options) {
+    const toWorkerOutput = (params) => ({
+        version: 'worker_output_v1',
+        status: params.status,
+        summary: params.summary,
+        deliverable: params.deliverable,
+        runId: params.runId ?? workerJob.id,
+        ...(params.error ? { error: params.error } : {})
+    });
+    try {
+        const isVerbose = workerJob.verbose;
+        //
+        // Créer le simulateur en mode worker
+        // - agents : [agent de production]
+        // - positionDescription : position description / cahier des charges (injecté dans WORKER_INTERNAL_PROMPT)
+        // - mode : 'worker' → WORKER_INTERNAL_PROMPT au lieu de GENERIC_SIMULATOR_PROMPT
+        const simulatorConfig = {
+            agents: [workerJob.agent],
+            start: workerJob.agent.name,
+            verbose: isVerbose,
+            mode: 'worker',
+            positionDescription: workerJob.positionDescription,
+            personaResult: workerJob.personaResult,
+            workerModel: workerJob.workerModel,
+            agentModel: workerJob.agentModel
+        };
+        const simulator = new simulator_1.AgentSimulator(simulatorConfig);
+        //
+        // Mode verbose : stream chaque message avec emoji par rôle
+        const ROLE_EMOJI = {
+            user: '🤖 Worker  ',
+            assistant: '🧠 Agent   ',
+            system: '⚙️  System  ',
+        };
+        const verboseOnMessage = isVerbose
+            ? (msg) => {
+                const emoji = ROLE_EMOJI[msg.role] ?? `❓ ${msg.role}`;
+                const preview = msg.content.length > 400
+                    ? msg.content.slice(0, 400) + '…'
+                    : msg.content;
+                console.log(`\n${emoji}: ${preview}`);
+            }
+            : undefined;
+        // Exécuter le job via simulator.runJob()
+        // - query : la demande de job (premier message à l'Agent)
+        // - positionDescription : déjà dans le system prompt du Worker LLM
+        const result = await simulator.runJob({
+            query,
+            maxIterations: workerJob.maxIterations,
+            agentContext,
+            jobId: workerJob.id,
+            description: workerJob.description,
+            onMessage: verboseOnMessage
+        });
+        if (result.success) {
+            const output = toWorkerOutput({
+                status: 'completed',
+                summary: result.summary,
+                deliverable: result.deliverable,
+                runId: result.execution?.runId
+            });
+            return {
+                status: 'ok',
+                items: [output],
+                meta: {
+                    jobId: workerJob.id,
+                    query,
+                    confidence: result.confidence,
+                    iterations: result.iterations,
+                    maxIterations: result.maxIterations,
+                    usage: result.execution?.usage,
+                    ...(options?.extend ? { messages: result.messages } : {})
+                },
+                control: {
+                    can_retry: false
+                }
+            };
+        }
+        //
+        // Job échoué ou timeout
+        const output = toWorkerOutput({
+            status: result.error?.includes('Max iterations reached') ? 'partial' : 'failed',
+            summary: result.summary || 'Worker execution failed',
+            deliverable: result.deliverable,
+            runId: result.execution?.runId,
+            error: result.error
+        });
+        return {
+            status: 'error',
+            meta: {
+                jobId: workerJob.id,
+                query,
+                iterations: result.iterations,
+                maxIterations: result.maxIterations,
+                duration: result.duration,
+                result: output,
+                ...(options?.extend ? { messages: result.messages } : {})
+            },
+            control: {
+                can_retry: true,
+                error_code: 'WORKER_FAILED',
+                next_hint: result.error
+            }
+        };
+    }
+    catch (error) {
+        const errorMessage = error?.message || 'Unknown worker exception';
+        const output = toWorkerOutput({
+            status: 'failed',
+            summary: 'Worker execution exception',
+            deliverable: '',
+            error: errorMessage
+        });
+        return {
+            status: 'error',
+            meta: {
+                jobId: workerJob.id,
+                query,
+                result: output
+            },
+            control: {
+                can_retry: true,
+                error_code: 'WORKER_EXCEPTION',
+                next_hint: errorMessage
+            }
+        };
+    }
+}

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

@@ -1,5 +1,7 @@
+import { ParsedFunctionToolCall } from 'openai/resources/beta/chat/completions';
 import { AgentStateGraph } from '../stategraph';
 import { AgentConfig, AgenticContext, ExecutionAction } from '../types';
+import { SubAgentCallResult } from '../agents/subagent';
 /**
  * OPTIM: Accumule l'usage des tokens et met à jour stateGraph + discussion.usage
  *
@@ -30,6 +32,7 @@ export declare function accumulateUsageTokens(stateGraph: AgentStateGraph, discu
  * @returns Array d'actions pour ExecutionResult
  */
 export declare function stepsToActions(stateGraph: AgentStateGraph, agentName: string): ExecutionAction[];
+export declare function handleSubAgentCall(stateGraph: AgentStateGraph, agents: AgentConfig[], functionCallParams: ParsedFunctionToolCall, context: AgenticContext): Promise<SubAgentCallResult>;
 /**
  * OPTIM: Traite tous les tool calls en batch et retourne les résultats
  *