agent-mp 0.5.12 → 0.5.15

package/dist/core/engine.d.ts

@@ -50,9 +50,16 @@ export declare class AgentEngine {
      * Allowed subdirectory files: <service>/architecture.md  (not touched here)
      */
     private _cleanContextDir;
+    /**
+     * Pre-read the actual file contents (manifests, env, entry points, controllers, schemas)
+     * for every component in the project, so the LLM does not need tool-use to inspect them.
+     * This is critical when the explorer runs against the Qwen API (no tools available)
+     * to avoid the LLM hallucinating tool calls instead of producing the real document.
+     */
+    private _prefetchProjectFiles;
     runExplorer(task?: string): Promise<string>;
-    /** Called when the current binary IS the configured explorer CLI (prevents recursion).
-     *  Builds the full exploration prompt and calls Qwen API using own credentials. */
+    /** Legacy entry point — delegates to runExplorer.
+     *  Kept for backward compatibility with anything that may still call it. */
     runExplorerDirect(task?: string): Promise<string>;
     runFullCycle(task: string): Promise<void>;
 }

package/dist/core/engine.js

@@ -202,6 +202,107 @@ function extractJson(text) {
         throw new Error('No JSON found');
     return JSON.parse(c.slice(first, last + 1));
 }
+/** Read a file safely, truncating to maxChars. Returns null if missing or empty. */
+async function readFileSafe(p, maxChars) {
+    try {
+        const content = await fs.readFile(p, 'utf-8');
+        if (!content || !content.trim())
+            return null;
+        if (content.length > maxChars) {
+            return content.slice(0, maxChars) + `\n... [truncado, ${content.length - maxChars} caracteres mas]`;
+        }
+        return content;
+    }
+    catch {
+        return null;
+    }
+}
+const PREFETCH_SKIP_DIRS = new Set([
+    '.agent', 'node_modules', '.git', 'dist', 'build', 'target',
+    '__pycache__', '.venv', 'venv', '.idea', '.vscode', '.next',
+    'coverage', '.cache', 'out', 'bin', 'obj',
+]);
+/** Walk a component dir looking for entry point, controllers, routers, schemas, models. */
+async function walkForKeyFiles(root) {
+    const result = {
+        entry: null,
+        controllers: [],
+        schemas: [],
+    };
+    const SOURCE_EXT = /\.(ts|tsx|js|jsx|py|go|java|kt|rs|cs)$/;
+    const SKIP_FILE = /\.(test|spec|d)\.[a-z]+$/i;
+    const ENTRY_NAMES = new Set([
+        'main.ts', 'main.js', 'main.py', 'main.go', 'Main.java',
+        'index.ts', 'index.js', 'index.py',
+        'app.ts', 'app.js', 'app.py',
+        'server.ts', 'server.js', 'server.py',
+        'application.ts', 'application.js', 'application.py',
+    ]);
+    const ENTRY_REGEX = /Application\.(java|kt)$/;
+    const CTRL_REGEX = /(controller|router|routes|handler|endpoint|resource)/i;
+    const SCHEMA_REGEX = /(schema|\.entity|\.model|\.dto|models?\.|entities?\.)/i;
+    async function walk(dir, depth) {
+        if (depth > 6)
+            return;
+        if (result.controllers.length >= 5 && result.schemas.length >= 5 && result.entry)
+            return;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const e of entries) {
+            if (e.name.startsWith('.'))
+                continue;
+            if (PREFETCH_SKIP_DIRS.has(e.name))
+                continue;
+            const p = path.join(dir, e.name);
+            if (e.isDirectory()) {
+                await walk(p, depth + 1);
+                continue;
+            }
+            if (!e.isFile())
+                continue;
+            if (!SOURCE_EXT.test(e.name))
+                continue;
+            if (SKIP_FILE.test(e.name))
+                continue;
+            // entry point detection
+            if (!result.entry && (ENTRY_NAMES.has(e.name) || ENTRY_REGEX.test(e.name))) {
+                result.entry = p;
+            }
+            if (CTRL_REGEX.test(e.name) && result.controllers.length < 5) {
+                result.controllers.push(p);
+            }
+            if (SCHEMA_REGEX.test(e.name) && result.schemas.length < 5) {
+                result.schemas.push(p);
+            }
+        }
+    }
+    await walk(root, 0);
+    return result;
+}
+/** Detect if the LLM hallucinated tool calls instead of producing the document content. */
+function looksLikeHallucinatedToolCalls(text) {
+    if (!text)
+        return true;
+    // Common hallucination patterns when the LLM thinks it's calling tools
+    const TOOL_PATTERNS = [
+        /===\s*TOOL_CALL\s*:/i,
+        /^\s*<tool_call>/m,
+        /^\s*<function_call>/m,
+        /^\s*```tool_use/im,
+    ];
+    if (TOOL_PATTERNS.some(re => re.test(text)))
+        return true;
+    // If the text has NO valid file markers at all, it's also a failure case
+    const fileMarkerMatches = text.match(/===\s+[^\n=]+?\.md\s*===/g);
+    if (!fileMarkerMatches || fileMarkerMatches.length === 0)
+        return true;
+    return false;
+}
 export class AgentEngine {
     config;
     projectDir;
@@ -969,6 +1070,114 @@ INSTRUCCIONES:
             }
         }
     }
+    /**
+     * Pre-read the actual file contents (manifests, env, entry points, controllers, schemas)
+     * for every component in the project, so the LLM does not need tool-use to inspect them.
+     * This is critical when the explorer runs against the Qwen API (no tools available)
+     * to avoid the LLM hallucinating tool calls instead of producing the real document.
+     */
+    async _prefetchProjectFiles() {
+        const MAX_MANIFEST = 5000;
+        const MAX_ENV = 2000;
+        const MAX_README = 3000;
+        const MAX_ENTRY = 3000;
+        const MAX_CTRL = 2500;
+        const MAX_SCHEMA = 1800;
+        let topEntries;
+        try {
+            topEntries = await fs.readdir(this.projectDir, { withFileTypes: true });
+        }
+        catch {
+            return '';
+        }
+        const sections = [];
+        // Top-level manifest / readme / docker (gives global context)
+        const TOP_GLOBAL_FILES = ['package.json', 'pom.xml', 'build.gradle', 'requirements.txt', 'go.mod', 'Cargo.toml', 'README.md', 'docker-compose.yml', 'docker-compose.yaml', 'Makefile'];
+        const topGlobal = [];
+        for (const fname of TOP_GLOBAL_FILES) {
+            const content = await readFileSafe(path.join(this.projectDir, fname), MAX_MANIFEST);
+            if (content)
+                topGlobal.push(`### ROOT: ${fname}\n\`\`\`\n${content}\n\`\`\``);
+        }
+        if (topGlobal.length > 0) {
+            sections.push(`## CONTEXTO GLOBAL DEL PROYECTO\n\n${topGlobal.join('\n\n')}`);
+        }
+        // Each top-level directory = candidate component
+        const components = topEntries
+            .filter(e => e.isDirectory() && !PREFETCH_SKIP_DIRS.has(e.name) && !e.name.startsWith('.'))
+            .sort((a, b) => a.name.localeCompare(b.name));
+        for (const comp of components) {
+            const compDir = path.join(this.projectDir, comp.name);
+            const compSection = [`## COMPONENTE: ${comp.name}`];
+            // Manifest
+            const MANIFESTS = ['package.json', 'requirements.txt', 'pyproject.toml', 'pom.xml', 'build.gradle', 'build.gradle.kts', 'Cargo.toml', 'go.mod', 'composer.json', 'Gemfile'];
+            let manifestFound = false;
+            for (const m of MANIFESTS) {
+                const content = await readFileSafe(path.join(compDir, m), MAX_MANIFEST);
+                if (content) {
+                    compSection.push(`### MANIFEST: ${m}\n\`\`\`\n${content}\n\`\`\``);
+                    manifestFound = true;
+                    break;
+                }
+            }
+            // README
+            const readme = await readFileSafe(path.join(compDir, 'README.md'), MAX_README)
+                || await readFileSafe(path.join(compDir, 'readme.md'), MAX_README);
+            if (readme)
+                compSection.push(`### README\n${readme}`);
+            // Env / config files (try several conventional locations)
+            const ENV_FILES = ['.env', '.env.example', '.env.sample', '.env.local', '.env.dev', 'application.yml', 'application.yaml', 'application.properties', 'config.yaml', 'config.yml'];
+            const ENV_DIRS = [compDir, path.join(compDir, 'src', 'main', 'resources'), path.join(compDir, 'config'), path.join(compDir, 'src', 'config')];
+            const seenEnv = new Set();
+            let envCount = 0;
+            for (const dir of ENV_DIRS) {
+                for (const f of ENV_FILES) {
+                    if (envCount >= 3)
+                        break;
+                    const p = path.join(dir, f);
+                    if (seenEnv.has(p))
+                        continue;
+                    seenEnv.add(p);
+                    const content = await readFileSafe(p, MAX_ENV);
+                    if (content) {
+                        const rel = path.relative(compDir, p);
+                        compSection.push(`### CONFIG/ENV: ${rel}\n\`\`\`\n${content}\n\`\`\``);
+                        envCount++;
+                    }
+                }
+            }
+            // Walk source for entry, controllers, schemas
+            const found = await walkForKeyFiles(compDir);
+            if (found.entry) {
+                const content = await readFileSafe(found.entry, MAX_ENTRY);
+                if (content) {
+                    const rel = path.relative(compDir, found.entry);
+                    compSection.push(`### ENTRY POINT: ${rel}\n\`\`\`\n${content}\n\`\`\``);
+                }
+            }
+            const ctrls = found.controllers.slice(0, 3);
+            for (const ctrl of ctrls) {
+                const content = await readFileSafe(ctrl, MAX_CTRL);
+                if (content) {
+                    const rel = path.relative(compDir, ctrl);
+                    compSection.push(`### CONTROLLER/ROUTER: ${rel}\n\`\`\`\n${content}\n\`\`\``);
+                }
+            }
+            const schemas = found.schemas.slice(0, 3);
+            for (const sch of schemas) {
+                const content = await readFileSafe(sch, MAX_SCHEMA);
+                if (content) {
+                    const rel = path.relative(compDir, sch);
+                    compSection.push(`### SCHEMA/MODEL: ${rel}\n\`\`\`\n${content}\n\`\`\``);
+                }
+            }
+            // Only add the component if we read at least the manifest or one source file
+            if (manifestFound || found.entry || found.controllers.length > 0 || found.schemas.length > 0) {
+                sections.push(compSection.join('\n\n'));
+            }
+        }
+        return sections.join('\n\n---\n\n');
+    }
     async runExplorer(task) {
         if (!this.config.roles.explorer) {
             if (!this.config.fallback_global) {
@@ -983,8 +1192,8 @@ INSTRUCCIONES:
         const contextDir = path.join(agentDir, 'context');
         await fs.mkdir(contextDir, { recursive: true });
         await fs.mkdir(path.join(agentDir, 'rules'), { recursive: true });
-        // Clean up stray files before running
-        await this._cleanContextDir(contextDir);
+        // NOTE: cleanup of stray files moved to AFTER successful parse, to avoid
+        // wiping previous docs when the explorer fails (e.g. tool-call hallucination).
         // Build a quick filesystem snapshot to give the explorer context
         let fsSnapshot = '';
         try {
@@ -992,6 +1201,17 @@ INSTRUCCIONES:
             fsSnapshot = execSync(`find "${this.projectDir}" -maxdepth 3 -not -path '*/.agent/*' -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/__pycache__/*' -not -path '*/.venv/*' -not -path '*/target/*' -not -path '*/build/*' -not -name '.git' | sort | head -300`, { encoding: 'utf-8', timeout: 10000 });
         }
         catch { /* ignore */ }
+        // Pre-read real file contents so the LLM has actual data instead of needing tools
+        const sp0 = this._startSpinner('explorer  pre-fetch  reading project files');
+        let prefetched = '';
+        try {
+            prefetched = await this._prefetchProjectFiles();
+            sp0.push(`${prefetched.split('## COMPONENTE:').length - 1} componente(s) leidos`);
+        }
+        catch (err) {
+            sp0.push(`prefetch error: ${err.message}`);
+        }
+        sp0.stop();
         // Read existing main architecture doc
         const mainArchPath = path.join(contextDir, 'architecture.md');
         let existingMainArch = '';
@@ -1024,6 +1244,8 @@ STACK: ${this.config.stack}
 ESTRUCTURA DE ARCHIVOS (excluye .agent, node_modules, .git, dist, __pycache__, .venv, target, build):
 ${fsSnapshot}
 
+${prefetched ? `================================================================\nARCHIVOS REALES LEIDOS DEL PROYECTO (esta es tu fuente de verdad)\n================================================================\n${prefetched}\n` : ''}
+
 ${existingMainArch ? `=== DOC EXISTENTE: architecture.md (principal) ===\n${existingMainArch.slice(0, 2000)}\n` : ''}
 ${existingComponentDocs ? `=== DOC EXISTENTE por componente ===\n${existingComponentDocs.slice(0, 3000)}\n` : ''}
 
@@ -1031,36 +1253,32 @@ ${existingComponentDocs ? `=== DOC EXISTENTE por componente ===\n${existingCompo
 OBJETIVO
 ================================================================
 Generar documentacion ESCALONADA en 3 niveles, util TANTO para personas funcionales (PM, negocio) como tecnicas (devs).
-Detallada pero NO excesiva. Concreta, con datos REALES leidos de los archivos. Cero especulaciones.
+Detallada pero NO excesiva. Concreta, con datos REALES extraidos de los archivos que estan mas arriba. Cero especulaciones.
 
 ================================================================
 REGLA DE ORO — PROHIBIDO INVENTAR
 ================================================================
 NO uses jamas: "Inferido", "Probablemente", "Posiblemente", "Asumido", "(supuesto)", "(quizas)", "parece ser".
-Si no podes verificar un dato leyendo un archivo concreto → OMITELO. Es mejor una doc corta y veraz que una larga llena de suposiciones.
-Cada puerto, version, endpoint, env var, schema o ruta que aparezca en la doc DEBE haber sido leido de un archivo real.
+Si un dato (puerto, version, endpoint, env var, schema, ruta) no aparece en los ARCHIVOS REALES de arriba → OMITILO.
+Es mejor una doc corta y veraz que una larga llena de suposiciones.
+NO devuelvas marcadores tipo "TOOL_CALL", "tool_use", "function_call" — vos NO tenes que llamar herramientas, tenes que devolver MARKDOWN.
 
 ================================================================
-WORKFLOW QUE TENES QUE EJECUTAR (usa tus tools de read_file/grep_search/list_directory)
+COMO TRABAJAR (lectura ya hecha por el engine)
 ================================================================
-1. Lista DIRECTORIO_TRABAJO. Identifica los componentes (apps/services/libs). Descarta lo trivial (solo configs/docs/scripts).
-2. Para CADA componente no trivial, LEE COMO MINIMO:
-   a. Manifest del proyecto: package.json | requirements.txt | pyproject.toml | pom.xml | build.gradle | Cargo.toml | go.mod
-      → de ahi sacas: nombre, version, framework, dependencias clave con sus versiones, scripts/tasks, entry point
-   b. Entry point real: src/main.ts | index.js | app.py | Application.java | cmd/main.go (segun stack)
-      → de ahi sacas: puerto, middlewares, modulos cargados, configuracion inicial
-   c. Archivo de variables de entorno: .env | .env.example | application.yml | config.* | settings.py
-      → de ahi sacas: variables reales con su proposito
-   d. Al menos 2-3 controladores/routers/handlers principales
-      → de ahi extraes endpoints REALES (metodo, ruta, parametros)
-   e. Al menos 2-3 modelos/schemas/entities principales
-      → de ahi extraes el shape de datos
-   f. README.md del componente si existe
-3. Mapea RELACIONES REALES entre componentes (no asumas):
-   - Buscando URLs/hosts de otros servicios en .env
-   - Buscando imports cross-component
-   - Buscando cadenas de conexion a BBDD/colas/cache
-4. Recien con esa informacion concreta, genera los archivos de documentacion.
+El engine YA leyo por vos los archivos clave de cada componente y te los pasa arriba en la seccion "ARCHIVOS REALES LEIDOS DEL PROYECTO". Tu tarea es:
+
+1. Identificar los componentes en la estructura de archivos.
+2. Para cada componente, extraer de sus archivos reales:
+   - Del MANIFEST: nombre, version, framework, dependencias clave con sus versiones, scripts, entry point
+   - Del ENTRY POINT: puerto real, middlewares, modulos cargados
+   - De los CONFIG/ENV: variables reales y su proposito
+   - De los CONTROLLER/ROUTER: endpoints REALES (metodo, ruta, parametros)
+   - De los SCHEMA/MODEL: shape real de los datos
+3. Identificar relaciones REALES entre componentes (URLs/hosts de otros servicios en .env, imports cross-component, conexiones a BBDD).
+4. Generar la documentacion en los 3 niveles, en formato markdown, dentro de los bloques === ... ===.
+
+NO inventes datos. Si un componente no tiene una de esas piezas en los archivos leidos, simplemente omiti esa seccion en su documentacion.
 
 ================================================================
 LENGUAJE DUAL (regla critica)
@@ -1264,33 +1482,56 @@ FORMATO DE SALIDA — OBLIGATORIO
 ================================================================
 Devolve UNICAMENTE bloques de archivos separados por marcadores ===. Nada de explicaciones extra fuera de los bloques.
 
-=== architecture.md ===
+IMPORTANTE: TODAS las rutas son RELATIVAS al directorio del proyecto.
+Los archivos se escriben SIEMPRE dentro de .agent/context/
+
+Ejemplos de marcadores:
+  === .agent/context/architecture.md ===
+  === .agent/context/datamart-data-access-api/architecture.md ===
+  === .agent/context/datamart-data-access-api/modules/auth.md ===
+  === .agent/context/nexus-core-api/architecture.md ===
+  === .agent/context/nexus-core-api/modules/users.md ===
+
+=== .agent/context/architecture.md ===
 [contenido completo del NIVEL 0]
 
-=== nombre-componente-1/architecture.md ===
+=== .agent/context/nombre-componente-1/architecture.md ===
 [contenido completo del NIVEL 1 del componente 1]
 
-=== nombre-componente-1/modules/auth.md ===
+=== .agent/context/nombre-componente-1/modules/auth.md ===
 [contenido completo del NIVEL 2 del modulo auth]
 
-=== nombre-componente-1/modules/leads.md ===
+=== .agent/context/nombre-componente-1/modules/leads.md ===
 [contenido completo del NIVEL 2 del modulo leads]
 
-=== nombre-componente-2/architecture.md ===
+=== .agent/context/nombre-componente-2/architecture.md ===
 ...
 
 REGLAS DE PATHS:
-- El archivo principal SIEMPRE es: === architecture.md ===
-- Por componente: === [nombre-componente]/architecture.md ===
-- Por modulo interno: === [nombre-componente]/modules/[nombre-modulo].md ===
-- USA SIEMPRE rutas RELATIVAS, jamas absolutas
+- El archivo principal SIEMPRE es: === .agent/context/architecture.md ===
+- Por componente: === .agent/context/[nombre-componente]/architecture.md ===
+- Por modulo interno: === .agent/context/[nombre-componente]/modules/[nombre-modulo].md ===
 - Documenta TODOS los componentes no triviales del DIRECTORIO_TRABAJO
 - Si existe documentacion previa, ACTUALIZALA preservando lo que sigue siendo valido y agregando lo nuevo`;
         const res = await this.runWithFallback('explorer', prompt, 'Exploracion');
         const text = extractCliText(res);
+        // Always overwrite the single last-run report so we have a debug trail
+        try {
+            await writeFile(path.join(contextDir, 'explorer-last.md'), `# Explorer Report\n\nTask: ${effectiveTask}\nDate: ${new Date().toISOString()}\n\n${text}\n`);
+        }
+        catch { /* don't fail if save fails */ }
+        // Detect tool-call hallucination or empty responses BEFORE touching anything
+        if (looksLikeHallucinatedToolCalls(text)) {
+            log.error('Explorer no devolvio bloques === *.md ===');
+            log.warn('Posible causa: el LLM intento llamar tools que no estan disponibles via API.');
+            log.warn(`Output guardado en: ${path.join(contextDir, 'explorer-last.md')}`);
+            log.warn('Documentacion previa preservada (no se modifico nada).');
+            return text;
+        }
         // Parse sections separated by === path/file.md === markers
         const sections = text.split(/===\s+(.+?\.md)\s*===/).slice(1);
-        let filesWritten = 0;
+        // First pass: collect all valid file writes WITHOUT touching disk yet (transactional)
+        const pendingWrites = [];
         for (let i = 0; i < sections.length; i += 2) {
             const fileName = sections[i].trim();
             let content = sections[i + 1] ? sections[i + 1].trim() : '';
@@ -1298,145 +1539,57 @@ REGLAS DE PATHS:
                 continue;
             // Clean up code fences if present
             content = content.replace(/^```markdown\s*/i, '').replace(/^```\s*$/gm, '').trim();
-            try {
-                let targetPath;
-                if (fileName === 'architecture.md' || fileName === 'ARCHITECTURE.md') {
-                    // Main architecture doc
-                    targetPath = mainArchPath;
+            if (!content)
+                continue;
+            // Normalize: strip any .agent/context/ prefix from the marker
+            let relPath = fileName.replace(/^\.agent\/context\//i, '').replace(/^\/+/, '');
+            let targetPath = null;
+            if (relPath === 'architecture.md' || relPath === 'ARCHITECTURE.md') {
+                targetPath = mainArchPath;
+            }
+            else {
+                const pathParts = relPath.split(/[\/\\]/).filter(Boolean);
+                if (pathParts.length >= 3 && pathParts[pathParts.length - 2] === 'modules') {
+                    targetPath = path.join(contextDir, pathParts[pathParts.length - 3], 'modules', pathParts[pathParts.length - 1]);
                 }
-                else {
-                    // CRITICAL: Extract only the relative path components, strip any absolute path prefix
-                    // fileName could be: "datamart-data-access-api/architecture.md"
-                    // or "/home/user/project/datamart-data-access-api/architecture.md" (BAD — must ignore prefix)
-                    // We only want the components relative to contextDir
-                    // Remove any leading absolute path by extracting the last meaningful path segments
-                    const cleanName = fileName.replace(/^.*[\/\\]/, ''); // strip any prefix
-                    // Check if it's a component architecture file: "component/architecture.md" or "component/modules/mod.md"
-                    const pathParts = fileName.split(/[\/\\]/).filter(Boolean);
-                    // Keep only the last 2-3 parts (component name + file)
-                    // e.g. ["/home", "user", "proj", "datamart", "architecture.md"] → ["datamart", "architecture.md"]
-                    // e.g. ["datamart-data-access-api", "architecture.md"] → same
-                    // e.g. ["datamart-data-access-api", "modules", "config.md"] → same
-                    let relPath;
-                    if (pathParts.length >= 3 && pathParts[pathParts.length - 2] === 'modules') {
-                        // component/modules/file.md
-                        relPath = path.join(pathParts[pathParts.length - 3], 'modules', pathParts[pathParts.length - 1]);
-                    }
-                    else if (pathParts.length >= 2) {
-                        // component/file.md
-                        relPath = path.join(pathParts[pathParts.length - 2], pathParts[pathParts.length - 1]);
-                    }
-                    else {
-                        // fallback
-                        relPath = path.join('modules', cleanName);
-                    }
-                    targetPath = path.join(contextDir, relPath);
+                else if (pathParts.length >= 2) {
+                    targetPath = path.join(contextDir, pathParts[pathParts.length - 2], pathParts[pathParts.length - 1]);
                 }
+            }
+            if (!targetPath)
+                continue;
+            pendingWrites.push({ targetPath, content, label: relPath });
+        }
+        if (pendingWrites.length === 0) {
+            log.error('Explorer devolvio texto pero ningun bloque === *.md === fue parseable.');
+            log.warn(`Output guardado en: ${path.join(contextDir, 'explorer-last.md')}`);
+            log.warn('Documentacion previa preservada (no se modifico nada).');
+            return text;
+        }
+        // Second pass: write everything to disk now that we know we have valid output
+        let filesWritten = 0;
+        for (const { targetPath, content, label } of pendingWrites) {
+            try {
                 await fs.mkdir(path.dirname(targetPath), { recursive: true });
                 await writeFile(targetPath, content);
                 filesWritten++;
             }
             catch (err) {
-                log.warn(`Failed to write ${fileName}: ${err.message}`);
+                log.warn(`Failed to write ${label}: ${err.message}`);
             }
         }
-        if (filesWritten > 0) {
-            log.ok(`${filesWritten} documentation file(s) written`);
-        }
-        // Overwrite the single last-run report (no timestamp accumulation)
+        log.ok(`${filesWritten} documentation file(s) written`);
+        // NOW it's safe to clean stray root-level .md files (after successful write).
         try {
-            await writeFile(path.join(contextDir, 'explorer-last.md'), `# Explorer Report\n\nTask: ${effectiveTask}\nDate: ${new Date().toISOString()}\n\n${text}\n`);
+            await this._cleanContextDir(contextDir);
         }
-        catch { /* don't fail if save fails */ }
+        catch { /* don't fail run if cleanup fails */ }
         return text;
     }
-    /** Called when the current binary IS the configured explorer CLI (prevents recursion).
-     *  Builds the full exploration prompt and calls Qwen API using own credentials. */
+    /** Legacy entry point — delegates to runExplorer.
+     *  Kept for backward compatibility with anything that may still call it. */
     async runExplorerDirect(task) {
-        const role = this.config.roles.explorer;
-        if (!role)
-            throw new Error('Explorer role not configured.');
-        const agentDir = path.join(this.projectDir, '.agent');
-        const contextDir = path.join(agentDir, 'context');
-        await fs.mkdir(contextDir, { recursive: true });
-        // Clean up stray files before running
-        await this._cleanContextDir(contextDir);
-        const archPath = path.join(contextDir, 'architecture.md');
-        let existingArch = '';
-        try {
-            existingArch = await readFile(archPath);
-        }
-        catch { /* new */ }
-        const effectiveTask = task || 'Explorar y documentar todas las aplicaciones y servicios del proyecto';
-        const context = await this.buildOrchestratorContext();
-        const prompt = this.buildRolePrompt('explorer', `TAREA DE EXPLORACION: ${effectiveTask}
-DIRECTORIO_TRABAJO: ${this.projectDir}
-PROYECTO: ${this.config.project}
-
-${existingArch ? `DOCUMENTACION EXISTENTE:\n${existingArch.slice(0, 3000)}\n` : 'Sin documentacion previa.\n'}
-CONTEXTO: ${context.slice(0, 2000)}
-
-OBJETIVO
-Generar documentacion ESCALONADA en 3 niveles (global / componente / modulo), util para perfiles funcionales y tecnicos. Detallada pero concreta. Cero suposiciones.
-
-REGLA DE ORO — PROHIBIDO ESPECULAR
-NO uses "Inferido", "Probablemente", "Asumido", "(quizas)", "parece". Si no podes verificar un dato leyendo un archivo, OMITELO. Cada puerto, version, endpoint, env var y schema debe haber sido leido de un archivo real.
-
-WORKFLOW (usa tus tools)
-1. Lista DIRECTORIO_TRABAJO y detecta los componentes no triviales.
-2. Para cada componente, LEE como minimo:
-   - Manifest (package.json | requirements.txt | pom.xml | build.gradle | go.mod | Cargo.toml)
-   - Entry point (main.ts | index.js | app.py | Application.java | cmd/main.go)
-   - .env / .env.example / application.yml / settings.py
-   - 2-3 controladores/routers principales (para endpoints reales)
-   - 2-3 schemas/models principales (para shapes reales)
-3. Mapea relaciones reales (URLs en .env, imports cross-component, conexiones a DB/colas).
-
-LENGUAJE DUAL
-Cada seccion abre con UNA linea simple (que entienda un PM). Despues, el detalle tecnico.
-- MAL: "El microservicio orquesta la persistencia mediante un repositorio."
-- BIEN: "Guarda la informacion del usuario. Internamente usa un repositorio que abstrae MongoDB."
-
-NIVEL 0 — ${archPath} (50-150 lineas)
-Secciones: Overview funcional · Tabla de componentes (con stack+version, puerto, proposito, entry point) · Tabla de relaciones (origen, destino, tipo, proposito) · Diagrama ASCII · 3-5 flujos end-to-end (mapping funcional → tecnico) · Prerequisitos · Comandos globales.
-
-NIVEL 1 — ${contextDir}/<componente>/architecture.md (80-200 lineas, uno por componente)
-Secciones: Que hace (simple) · Casos de uso (3-6 bullets en formato negocio) · Stack tecnico (tabla con versiones reales) · Puerto y URLs · Estructura interna (arbol real) · Tabla de modulos · Tabla de endpoints reales · Tabla de variables de entorno · Integraciones · Como levantar · Comandos.
-
-NIVEL 2 — ${contextDir}/<componente>/modules/<modulo>.md (40-120 lineas, uno por modulo significativo)
-Secciones: Funcion (simple) · Funcion (tecnica) · Flujos / casos de uso paso a paso · Endpoints / interfaces · Schemas reales en codigo · Reglas de negocio · Archivos clave · Dependencias internas/externas/cross-component.
-
-CALIBRACION
-- NIVEL 0: 50-150 lineas. NIVEL 1: 80-200 por componente. NIVEL 2: 40-120 por modulo.
-- Si te queda corto, leiste pocos archivos. Si te queda largo, recorta el relleno.
-- Componentes triviales (solo scripts/docs): mencionalos en NIVEL 0 y NO les crees subcarpeta.
-
-REGLAS DE ESCRITURA
-- Solo podes escribir archivos dentro de ${contextDir}/
-- NO crees archivos sueltos en la raiz de ${contextDir}/ (excepto architecture.md)
-- Por componente usa: ${contextDir}/<componente>/architecture.md
-- Por modulo usa: ${contextDir}/<componente>/modules/<modulo>.md
-- Si existe documentacion previa, ACTUALIZALA preservando lo valido`);
-        let result;
-        const sp = this._startSpinner(`agent-explorer  ${role.model}`);
-        try {
-            result = await callQwenAPI(prompt, role.model, (c) => this._parseChunk(c).forEach(l => sp.push(l)));
-            sp.stop();
-        }
-        catch (err) {
-            sp.stop();
-            if (err.message?.startsWith('QWEN_AUTH_EXPIRED')) {
-                console.log(chalk.red('\n  ✗ Sesión Qwen expirada.'));
-                console.log(chalk.yellow('  Ejecutá: agent-mp --login  (o agent-explorer --login)\n'));
-                return '';
-            }
-            throw err;
-        }
-        try {
-            await writeFile(path.join(contextDir, 'explorer-last.md'), `# Explorer Report\n\nTask: ${effectiveTask}\nDate: ${new Date().toISOString()}\n\n${result}\n`);
-        }
-        catch { /* ignore */ }
-        return result;
+        return this.runExplorer(task);
     }
     async runFullCycle(task) {
         // Header is now shown by the REPL before the first user message

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-mp",
-  "version": "0.5.12",
+  "version": "0.5.15",
   "description": "Deterministic multi-agent CLI orchestrator — plan, code, review",
   "type": "module",
   "main": "./dist/index.js",
@@ -8,7 +8,7 @@
     "dist/"
   ],
   "bin": {
-    "agent-mp": "dist/index.js"
+    "agent-explorer": "dist/index.js"
   },
   "scripts": {
     "build": "tsc && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/index.tmp && mv dist/index.tmp dist/index.js && chmod +x dist/index.js",