feat(glob): auto-summarize large file lists with AnalysisAgent #453

Trigger AnalysisAgent to summarize glob results when file count or character count exceeds thresholds. Update documentation with smart file search and agent collaboration guidelines. Add explicit handling for ask-agent and task-boundary tools in orchestrator.

Author: phodal

mpp-core/src/commonMain/kotlin/cc/unitmesh/agent/CodingAgentTemplate.kt

@@ -44,6 +44,66 @@ Each tool's parameters are validated against its JSON Schema. Refer to the schem
 4. **Test Your Changes**: Run tests or build commands to verify changes
 5. **Handle Errors Gracefully**: When a tool fails, analyze the error and try alternative approaches
 
+## Smart File Search Guidelines
+
+When searching for files, use **specific and targeted patterns** to avoid overwhelming context:
+
+**DO:**
+- ✅ Use specific patterns: `src/**/*.kt`, `**/test/**/*.java`, `**/config/*.yml`
+- ✅ Target specific directories: `/glob pattern="*.ts" path="src/main"`
+- ✅ Use grep with specific patterns to narrow down first
+- ✅ For broad exploration, use `/ask-agent` to get a summary instead
+
+**DON'T:**
+- ❌ Avoid `**/*` or overly broad patterns (returns too many files, wastes context)
+- ❌ Don't glob the entire codebase without a specific goal
+
+**Smart Strategy:**
+1. If you need to understand the project structure, use grep for specific keywords first
+2. Use targeted glob patterns based on what you found
+3. For very large result sets (100+ files), the system will automatically invoke a SummaryAgent to provide a concise overview
+
+## Agent Communication & Collaboration
+
+When dealing with complex information or large content, you can **communicate with specialized SubAgents** to get focused analysis:
+
+**Available SubAgents:**
+- `analysis-agent`: Analyzes and summarizes any content (logs, file lists, code, data)
+- `error-agent`: Analyzes errors and provides recovery suggestions
+- `code-agent`: Deep codebase investigation and architectural analysis
+
+**When to Use `/ask-agent`:**
+1. **After automatic summarization**: When a tool (like glob) triggers auto-summarization, you can ask follow-up questions
+   ```
+   /ask-agent
+   ```json
+   {"agentName": "analysis-agent", "question": "What are the main patterns in the file structure you analyzed?"}
+   ```
+   ```
+
+2. **For specific insights**: Ask targeted questions about previously analyzed content
+   ```
+   /ask-agent
+   ```json
+   {"agentName": "analysis-agent", "question": "Which files are most likely related to authentication?"}
+   ```
+   ```
+
+3. **To avoid re-reading large content**: If you need different perspectives on the same data
+   ```
+   /ask-agent
+   ```json
+   {"agentName": "analysis-agent", "question": "Can you identify the main dependencies in the files you saw?"}
+   ```
+   ```
+
+**Example Workflow:**
+1. `/glob pattern="**/*.kt"` → Auto-triggers AnalysisAgent (returns summary)
+2. Review the summary, then ask: `/ask-agent` to get specific insights
+3. Based on insights, use targeted `/read-file` or `/grep` commands
+
+This approach keeps your context efficient while getting deep insights from specialized agents!
+
 ## Task Progress Communication
 
 For complex multi-step tasks (5+ steps), use `/task-boundary` to help users understand your progress:
@@ -163,6 +223,66 @@ ${'$'}{toolList}
 3. **增量更改**: 一次做一个更改并验证其有效性
 4. **测试更改**: 运行测试或构建命令来验证更改
 
+## 智能文件搜索指南
+
+搜索文件时，使用**具体且有针对性的模式**以避免上下文超载：
+
+**应该做：**
+- ✅ 使用具体的模式：`src/**/*.kt`、`**/test/**/*.java`、`**/config/*.yml`
+- ✅ 针对特定目录：`/glob pattern="*.ts" path="src/main"`
+- ✅ 先使用 grep 配合具体模式来缩小范围
+- ✅ 对于广泛探索，使用 `/ask-agent` 获取摘要
+
+**不应该做：**
+- ❌ 避免 `**/*` 或过于宽泛的模式（返回太多文件，浪费上下文）
+- ❌ 不要在没有明确目标的情况下 glob 整个代码库
+
+**智能策略：**
+1. 如果需要了解项目结构，先使用 grep 搜索特定关键词
+2. 根据发现的内容使用有针对性的 glob 模式
+3. 对于非常大的结果集（100+ 文件），系统会自动调用 SummaryAgent 提供简洁概述
+
+## Agent 通信与协作
+
+处理复杂信息或大量内容时，你可以**与专业的 SubAgent 通信**来获取专注的分析：
+
+**可用的 SubAgent:**
+- `analysis-agent`: 分析和总结任何内容（日志、文件列表、代码、数据）
+- `error-agent`: 分析错误并提供恢复建议
+- `code-agent`: 深度代码库调查和架构分析
+
+**何时使用 `/ask-agent`:**
+1. **自动总结之后**: 当工具（如 glob）触发自动总结后，你可以询问后续问题
+   ```
+   /ask-agent
+   ```json
+   {"agentName": "analysis-agent", "question": "你分析的文件结构中有哪些主要模式？"}
+   ```
+   ```
+
+2. **获取特定见解**: 就之前分析的内容提出针对性问题
+   ```
+   /ask-agent
+   ```json
+   {"agentName": "analysis-agent", "question": "哪些文件最可能与身份验证相关？"}
+   ```
+   ```
+
+3. **避免重复读取大内容**: 需要从不同角度看待相同数据时
+   ```
+   /ask-agent
+   ```json
+   {"agentName": "analysis-agent", "question": "你能识别出文件中的主要依赖关系吗？"}
+   ```
+   ```
+
+**示例工作流:**
+1. `/glob pattern="**/*.kt"` → 自动触发 AnalysisAgent（返回摘要）
+2. 查看摘要，然后询问：`/ask-agent` 获取特定见解
+3. 基于见解，使用有针对性的 `/read-file` 或 `/grep` 命令
+
+这种方法既保持上下文高效，又能从专业 Agent 获得深度见解！
+
 ## 任务进度沟通
 
 对于复杂的多步骤任务（5+ 步骤），使用 `/task-boundary` 帮助用户了解你的进度：

mpp-core/src/commonMain/kotlin/cc/unitmesh/agent/orchestrator/ToolOrchestrator.kt

@@ -253,10 +253,16 @@ class ToolOrchestrator(
                 ToolType.Glob -> executeGlobTool(tool, params, basicContext)
                 ToolType.Grep -> executeGrepTool(tool, params, basicContext)
                 ToolType.WebFetch -> executeWebFetchTool(tool, params, basicContext)
+                ToolType.AskAgent -> executeAskAgentTool(tool, params, basicContext)
                 else -> {
-                    // For new tools (task-boundary, ask-agent, etc.), use generic execution
-                    logger.debug { "Executing tool generically: $toolName" }
-                    executeGenericTool(tool, params, basicContext)
+                    // Handle special tools that need parameter conversion
+                    if (toolName == "task-boundary") {
+                        executeTaskBoundaryTool(tool, params, basicContext)
+                    } else {
+                        // For truly generic tools, use generic execution
+                        logger.debug { "Executing tool generically: $toolName" }
+                        executeGenericTool(tool, params, basicContext)
+                    }
                 }
             }
         }
@@ -512,6 +518,52 @@ class ToolOrchestrator(
         return invocation.execute(context)
     }
 
+    private suspend fun executeAskAgentTool(
+        tool: Tool,
+        params: Map<String, Any>,
+        context: cc.unitmesh.agent.tool.ToolExecutionContext
+    ): ToolResult {
+        val askAgentTool = tool as cc.unitmesh.agent.tool.impl.AskAgentTool
+        
+        val agentName = params["agentName"] as? String
+            ?: return ToolResult.Error("agentName parameter is required")
+        val question = params["question"] as? String
+            ?: return ToolResult.Error("question parameter is required")
+        val contextMap = params["context"] as? Map<*, *>
+        
+        val askAgentParams = cc.unitmesh.agent.tool.impl.AskSubAgentParams(
+            agentName = agentName,
+            question = question,
+            context = contextMap?.mapKeys { it.key.toString() }?.mapValues { it.value.toString() } ?: emptyMap()
+        )
+        
+        val invocation = askAgentTool.createInvocation(askAgentParams)
+        return invocation.execute(context)
+    }
+
+    private suspend fun executeTaskBoundaryTool(
+        tool: Tool,
+        params: Map<String, Any>,
+        context: cc.unitmesh.agent.tool.ToolExecutionContext
+    ): ToolResult {
+        val taskBoundaryTool = tool as cc.unitmesh.agent.tool.impl.TaskBoundaryTool
+        
+        val taskName = params["taskName"] as? String
+            ?: return ToolResult.Error("taskName parameter is required")
+        val status = params["status"] as? String
+            ?: return ToolResult.Error("status parameter is required")
+        val summary = params["summary"] as? String ?: ""
+        
+        val taskBoundaryParams = cc.unitmesh.agent.tool.impl.TaskBoundaryParams(
+            taskName = taskName,
+            status = status,
+            summary = summary
+        )
+        
+        val invocation = taskBoundaryTool.createInvocation(taskBoundaryParams)
+        return invocation.execute(context)
+    }
+
     private fun isSuccessResult(result: ToolResult): Boolean {
         return when (result) {
             is ToolResult.Success -> true

mpp-core/src/commonMain/kotlin/cc/unitmesh/agent/tool/impl/GlobTool.kt

@@ -86,9 +86,17 @@ class GlobInvocation(
     params: GlobParams,
     tool: GlobTool,
     private val fileSystem: ToolFileSystem,
-    private val gitIgnoreParser: GitIgnoreParser? = null
+    private val gitIgnoreParser: GitIgnoreParser? = null,
+    private val analysisAgent: cc.unitmesh.agent.subagent.AnalysisAgent? = null
 ) : BaseToolInvocation<GlobParams, ToolResult>(params, tool) {
 
+    companion object {
+        // Threshold for triggering AnalysisAgent (file count)
+        const val FILE_COUNT_THRESHOLD = 100
+        // Threshold for triggering AnalysisAgent (character count)
+        const val CHAR_COUNT_THRESHOLD = 10000
+    }
+
     override fun getDescription(): String {
         val searchPath = params.path ?: "project root"
         val typeDesc = if (params.includeDirectories) "files and directories" else "files"
@@ -118,7 +126,7 @@ class GlobInvocation(
             val limitedMatches = sortedMatches.take(params.maxResults)
             val resultText = formatResults(limitedMatches, matches.size)
 
-            val metadata = mapOf(
+            val metadata = mutableMapOf(
                 "pattern" to params.pattern,
                 "search_path" to searchPath,
                 "total_matches" to matches.size.toString(),
@@ -129,7 +137,49 @@ class GlobInvocation(
                 "respect_gitignore" to params.respectGitIgnore.toString()
             )
 
-            ToolResult.Success(resultText, metadata)
+            // Check if result is too long and should trigger AnalysisAgent
+            val shouldSummarize = limitedMatches.size >= FILE_COUNT_THRESHOLD || 
+                                  resultText.length >= CHAR_COUNT_THRESHOLD
+                                  
+            if (shouldSummarize && analysisAgent != null) {
+                metadata["triggered_analysis"] = "true"
+                metadata["original_result_length"] = resultText.length.toString()
+                
+                // Trigger AnalysisAgent to summarize the results
+                val analysisContext = cc.unitmesh.agent.subagent.ContentHandlerContext(
+                    content = resultText,
+                    contentType = "file-list",
+                    source = "glob",
+                    metadata = metadata.mapValues { it.value.toString() }
+                )
+                
+                val analysisResult = analysisAgent.execute(analysisContext) { progress ->
+                    // Log progress if needed
+                }
+                
+                if (analysisResult.success) {
+                    // Return summarized result with reference to full list
+                    val summarizedText = buildString {
+                        appendLine("⚠️ Large file list detected (${limitedMatches.size} files, ${resultText.length} chars)")
+                        appendLine("🤖 AnalysisAgent automatically triggered to provide a summary:")
+                        appendLine()
+                        appendLine(analysisResult.content)
+                        appendLine()
+                        appendLine("💡 Tip: Use more specific glob patterns to reduce result size:")
+                        appendLine("  - Instead of: **/*")
+                        appendLine("  - Try: src/**/*.kt or **/test/**/*.java")
+                        appendLine()
+                        appendLine("📋 Full file list available in metadata if needed.")
+                    }
+                    
+                    metadata["full_result"] = resultText
+                    metadata["analysis_metadata"] = analysisResult.metadata.toString()
+                    
+                    return@safeExecute ToolResult.Success(summarizedText, metadata.toMap())
+                }
+            }
+
+            ToolResult.Success(resultText, metadata.toMap())
         }
     }
 
@@ -284,12 +334,15 @@ class GlobInvocation(
 }
 
 class GlobTool(
-    private val fileSystem: ToolFileSystem
+    private val fileSystem: ToolFileSystem,
+    private val analysisAgent: cc.unitmesh.agent.subagent.AnalysisAgent? = null
 ) : BaseExecutableTool<GlobParams, ToolResult>() {
 
     override val name: String = "glob"
     override val description: String =
-        """Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `**/*.md`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases.""".trimIndent()
+        """Efficiently finds files matching specific glob patterns (e.g., `src/**/*.ts`, `**/*.md`), returning absolute paths sorted by modification time (newest first). Ideal for quickly locating files based on their name or path structure, especially in large codebases. 
+        
+⚠️ IMPORTANT: Avoid overly broad patterns like `**/*` as they can return too many files and waste context. Use specific patterns instead. When results are too large (100+ files), the system automatically triggers AnalysisAgent to provide a concise summary.""".trimIndent()
 
     override val metadata: ToolMetadata = ToolMetadata(
         displayName = "Find Files",
@@ -321,7 +374,7 @@ class GlobTool(
             null
         }
 
-        return GlobInvocation(params, this, fileSystem, gitIgnoreParser)
+        return GlobInvocation(params, this, fileSystem, gitIgnoreParser, analysisAgent)
     }
 
     private fun validateParameters(params: GlobParams) {

mpp-core/src/commonMain/kotlin/cc/unitmesh/agent/tool/registry/BuiltinToolsProvider.kt

@@ -32,7 +32,10 @@ class BuiltinToolsProvider : ToolProvider {
 
         // Search tools
         tools.add(GrepTool(dependencies.fileSystem))
-        tools.add(GlobTool(dependencies.fileSystem))
+        
+        // GlobTool with AnalysisAgent support for auto-summarization of large results
+        val analysisAgent = dependencies.subAgentManager?.getSubAgent<cc.unitmesh.agent.subagent.ContentHandlerContext, cc.unitmesh.agent.tool.ToolResult.AgentResult>("analysis-agent") as? cc.unitmesh.agent.subagent.AnalysisAgent
+        tools.add(GlobTool(dependencies.fileSystem, analysisAgent))
 
         if (dependencies.shellExecutor.isAvailable()) {
             tools.add(ShellTool(dependencies.shellExecutor))

mpp-core/src/jsMain/kotlin/cc/unitmesh/agent/config/ToolConfigExports.kt

@@ -128,7 +128,6 @@ class JsToolConfigFile(
         }
 
         return ToolConfigFile(
-            enabledBuiltinTools = enabledBuiltinTools.toList(),
             enabledMcpTools = enabledMcpTools.toList(),
             mcpServers = mcpServersMap,
         )
@@ -149,7 +148,7 @@ class JsToolConfigFile(
             }
 
             return JsToolConfigFile(
-                enabledBuiltinTools = config.enabledBuiltinTools.toTypedArray(),
+                enabledBuiltinTools = emptyArray(), // Deprecated: Built-in tools are always enabled
                 enabledMcpTools = config.enabledMcpTools.toTypedArray(),
                 mcpServers = mcpServersJs
             )