Skip to main content

microclaw_engine/tools/
explore.rs

1//! `explore`: a synchronous, read-only sub-agent for wide searches.
2//!
3//! The calling agent hands over a question ("where is the retry policy
4//! configured and who calls it?"); a fresh loop with only read/search tools
5//! answers it and returns a short report. The main conversation receives the
6//! conclusion instead of every file it took to get there, which keeps its
7//! context small. The tool is read-only, so several `explore` calls in one
8//! reply run in parallel.
9//!
10//! Project agents: a trusted workspace can define focused helpers in
11//! `.microclaw/agents/<name>.md` (front matter `description`, optional
12//! `model`; the body is the system prompt), selected with `agent`.
13
14use std::path::{Path, PathBuf};
15use std::sync::Arc;
16
17use async_trait::async_trait;
18use serde_json::json;
19
20use super::{schema_object, Tool, ToolRegistry, ToolResult};
21use crate::config::Config;
22use crate::internal::storage::db::Database;
23use crate::internal::tool_runtime::runtime::{
24    auth_context_from_input, tool_concurrency_class, ToolAuthContext, ToolConcurrencyClass,
25};
26use microclaw_core::llm_types::{
27    ContentBlock, Message, MessageContent, ResponseContentBlock, ToolDefinition,
28};
29
30const MAX_ITERATIONS: usize = 30;
31const MAX_REPORT_CHARS: usize = 16_000;
32/// Tool output kept per call inside the explore loop.
33const MAX_TOOL_OUTPUT_CHARS: usize = 24_000;
34
35const DEFAULT_PROMPT: &str = "You are an exploration helper working for another agent. Answer its question by reading and searching the workspace (read_file, grep, glob, and web tools when the question needs them). You cannot change anything. Be efficient: search before reading, read only what you need. Finish with a concise report: the answer, the exact file paths and line numbers that support it, and anything uncertain. No preamble.";
36
37/// A project-defined helper agent.
38#[derive(Debug, Clone, PartialEq, Eq)]
39pub struct ProjectAgent {
40    pub name: String,
41    pub description: String,
42    pub model: Option<String>,
43    pub prompt: String,
44}
45
46/// Agents defined in `dir` (`<name>.md` with optional front matter).
47pub fn load_project_agents(dir: &Path) -> Vec<ProjectAgent> {
48    let Ok(entries) = std::fs::read_dir(dir) else {
49        return Vec::new();
50    };
51    let mut agents: Vec<ProjectAgent> = entries
52        .filter_map(|entry| entry.ok())
53        .map(|entry| entry.path())
54        .filter(|path| path.extension().is_some_and(|ext| ext == "md"))
55        .filter_map(|path| {
56            let name = path.file_stem()?.to_str()?.to_string();
57            let text = std::fs::read_to_string(&path).ok()?;
58            Some(parse_agent(&name, &text))
59        })
60        .filter(|agent| !agent.prompt.trim().is_empty())
61        .collect();
62    agents.sort_by(|a, b| a.name.cmp(&b.name));
63    agents
64}
65
66fn parse_agent(name: &str, text: &str) -> ProjectAgent {
67    let mut description = String::new();
68    let mut model = None;
69    let mut body = text;
70    if let Some(rest) = text.strip_prefix("---") {
71        if let Some(end) = rest.find("\n---") {
72            for line in rest[..end].lines() {
73                if let Some((key, value)) = line.split_once(':') {
74                    let value = value.trim().trim_matches('"').to_string();
75                    match key.trim() {
76                        "description" => description = value,
77                        "model" if !value.is_empty() => model = Some(value),
78                        _ => {}
79                    }
80                }
81            }
82            body = rest[end + 4..].trim_start_matches(['\r', '\n']);
83        }
84    }
85    ProjectAgent {
86        name: name.to_string(),
87        description,
88        model,
89        prompt: body.trim().to_string(),
90    }
91}
92
93pub struct ExploreTool {
94    config: Config,
95    db: Arc<Database>,
96    agents: Vec<ProjectAgent>,
97}
98
99impl ExploreTool {
100    pub fn new(config: &Config, db: Arc<Database>) -> Self {
101        let agents = config
102            .project_agents_dir
103            .as_deref()
104            .map(|dir| load_project_agents(&PathBuf::from(dir)))
105            .unwrap_or_default();
106        Self {
107            config: config.clone(),
108            db,
109            agents,
110        }
111    }
112}
113
114fn truncate(text: &str, max: usize) -> String {
115    crate::context_window::truncate_chars(text, max)
116}
117
118#[async_trait]
119impl Tool for ExploreTool {
120    fn name(&self) -> &str {
121        "explore"
122    }
123
124    fn definition(&self) -> ToolDefinition {
125        let mut description = String::from(
126            "Delegate a read-only investigation to a helper with its own context: finding where something is defined or used, understanding a subsystem, surveying many files. Returns a short report with file paths and line numbers, so your own context only gets the conclusion. Several explore calls in one reply run in parallel. The helper cannot edit files or run commands. Give it a precise question.",
127        );
128        if !self.agents.is_empty() {
129            description.push_str(" Project agents (pass as `agent`): ");
130            let list: Vec<String> = self
131                .agents
132                .iter()
133                .map(|a| {
134                    if a.description.is_empty() {
135                        a.name.clone()
136                    } else {
137                        format!("{} ({})", a.name, a.description)
138                    }
139                })
140                .collect();
141            description.push_str(&list.join("; "));
142            description.push('.');
143        }
144        let mut properties = json!({
145            "task": {
146                "type": "string",
147                "description": "The question to answer, with any paths or names you already know"
148            }
149        });
150        if !self.agents.is_empty() {
151            properties["agent"] = json!({
152                "type": "string",
153                "enum": self.agents.iter().map(|a| a.name.clone()).collect::<Vec<_>>(),
154                "description": "Project agent to use instead of the default explorer"
155            });
156        }
157        ToolDefinition {
158            name: "explore".into(),
159            description,
160            input_schema: schema_object(properties, &["task"]),
161        }
162    }
163
164    async fn execute(&self, input: serde_json::Value) -> ToolResult {
165        let Some(task) = input
166            .get("task")
167            .and_then(|v| v.as_str())
168            .map(str::trim)
169            .filter(|t| !t.is_empty())
170        else {
171            return ToolResult::error("explore: `task` is required".into());
172        };
173        let agent = match input.get("agent").and_then(|v| v.as_str()) {
174            Some(name) => match self.agents.iter().find(|a| a.name == name) {
175                Some(agent) => Some(agent.clone()),
176                None => return ToolResult::error(format!("explore: unknown agent `{name}`")),
177            },
178            None => None,
179        };
180        let parent = auth_context_from_input(&input);
181        let auth = ToolAuthContext {
182            caller_channel: parent
183                .as_ref()
184                .map(|a| a.caller_channel.clone())
185                .unwrap_or_else(|| "code".into()),
186            caller_chat_id: parent.as_ref().map(|a| a.caller_chat_id).unwrap_or(0),
187            principal: "subagent:explore".into(),
188            control_chat_ids: Vec::new(),
189            env_files: Vec::new(),
190        };
191        match run_explore(&self.config, self.db.clone(), &auth, task, agent.as_ref()).await {
192            Ok(report) => ToolResult::success(report),
193            Err(e) => ToolResult::error(format!("explore failed: {e}")),
194        }
195    }
196}
197
198/// Read-only tools the explorer may use.
199fn explorer_tool(name: &str) -> bool {
200    tool_concurrency_class(name) == ToolConcurrencyClass::ReadOnly
201        && matches!(
202            name,
203            "read_file" | "grep" | "glob" | "web_fetch" | "web_search" | "fetch_artifact"
204        )
205}
206
207async fn run_explore(
208    config: &Config,
209    db: Arc<Database>,
210    auth: &ToolAuthContext,
211    task: &str,
212    agent: Option<&ProjectAgent>,
213) -> anyhow::Result<String> {
214    let tools = ToolRegistry::new_sub_agent(config, db.clone(), None, false);
215    let tool_defs: Vec<ToolDefinition> = tools
216        .definitions_for(auth)
217        .into_iter()
218        .filter(|d| explorer_tool(&d.name))
219        .collect();
220    let llm = crate::llm::create_provider(config);
221    let model = agent
222        .and_then(|a| a.model.clone())
223        .unwrap_or_else(|| config.model.clone());
224    let system = match agent {
225        Some(agent) => format!(
226            "{}\n\nYou are working for another agent and cannot change anything; only read and search. End with a concise report including file paths and line numbers.",
227            agent.prompt
228        ),
229        None => DEFAULT_PROMPT.to_string(),
230    };
231    let mut messages = vec![Message {
232        role: "user".into(),
233        content: MessageContent::Text(task.to_string()),
234    }];
235    let mut files_read = 0usize;
236    for _ in 0..MAX_ITERATIONS {
237        let response = llm
238            .send_message_with_model(
239                &system,
240                messages.clone(),
241                Some(tool_defs.clone()),
242                Some(&model),
243            )
244            .await?;
245        if let Some(usage) = &response.usage {
246            let (channel, provider, model_name) = (
247                auth.caller_channel.clone(),
248                config.llm_provider.clone(),
249                model.clone(),
250            );
251            let (chat_id, input_tokens, output_tokens) = (
252                auth.caller_chat_id,
253                i64::from(usage.input_tokens),
254                i64::from(usage.output_tokens),
255            );
256            let _ = crate::internal::storage::db::call_blocking(db.clone(), move |db| {
257                db.log_llm_usage(
258                    chat_id,
259                    &channel,
260                    &provider,
261                    &model_name,
262                    input_tokens,
263                    output_tokens,
264                    "explore",
265                )
266                .map(|_| ())
267            })
268            .await;
269        }
270        let mut text = String::new();
271        let mut calls = Vec::new();
272        for block in &response.content {
273            match block {
274                ResponseContentBlock::Text { text: t } => text.push_str(t),
275                ResponseContentBlock::ToolUse {
276                    id, name, input, ..
277                } => calls.push((id.clone(), name.clone(), input.clone())),
278                _ => {}
279            }
280        }
281        if calls.is_empty() {
282            let report = if text.trim().is_empty() {
283                "(the explorer found nothing to report)".to_string()
284            } else {
285                truncate(text.trim(), MAX_REPORT_CHARS)
286            };
287            return Ok(format!("{report}\n\n[explore: {files_read} tool calls]"));
288        }
289        let mut assistant_blocks = Vec::new();
290        if !text.trim().is_empty() {
291            assistant_blocks.push(ContentBlock::Text { text: text.clone() });
292        }
293        for (id, name, input) in &calls {
294            assistant_blocks.push(ContentBlock::ToolUse {
295                id: id.clone(),
296                name: name.clone(),
297                input: input.clone(),
298                thought_signature: None,
299            });
300        }
301        messages.push(Message {
302            role: "assistant".into(),
303            content: MessageContent::Blocks(assistant_blocks),
304        });
305        let results = futures_util::future::join_all(calls.iter().map(|(_, name, input)| {
306            let name = name.clone();
307            let input = input.clone();
308            let tools = &tools;
309            async move {
310                if !explorer_tool(&name) {
311                    return ToolResult::error(format!(
312                        "`{name}` is not available to the explorer (read-only tools only)"
313                    ));
314                }
315                tools.execute_with_auth(&name, input, auth).await
316            }
317        }))
318        .await;
319        files_read += calls.len();
320        let result_blocks = calls
321            .iter()
322            .zip(results)
323            .map(|((id, _, _), result)| ContentBlock::ToolResult {
324                tool_use_id: id.clone(),
325                content: truncate(&result.content, MAX_TOOL_OUTPUT_CHARS),
326                is_error: result.is_error.then_some(true),
327            })
328            .collect();
329        messages.push(Message {
330            role: "user".into(),
331            content: MessageContent::Blocks(result_blocks),
332        });
333    }
334    anyhow::bail!("no report after {MAX_ITERATIONS} steps; ask a narrower question")
335}
336
337#[cfg(test)]
338mod tests {
339    use super::*;
340
341    #[test]
342    fn parses_agent_front_matter() {
343        let agent = parse_agent(
344            "db-expert",
345            "---\ndescription: Knows the storage layer\nmodel: small-model\n---\nYou explain the database code.\n",
346        );
347        assert_eq!(agent.description, "Knows the storage layer");
348        assert_eq!(agent.model.as_deref(), Some("small-model"));
349        assert_eq!(agent.prompt, "You explain the database code.");
350        let plain = parse_agent("plain", "Just a prompt.");
351        assert_eq!(plain.prompt, "Just a prompt.");
352        assert!(plain.description.is_empty());
353    }
354
355    #[test]
356    fn loads_agents_from_a_directory() {
357        let dir = tempfile::tempdir().unwrap();
358        std::fs::write(
359            dir.path().join("a.md"),
360            "---\ndescription: A\n---\nPrompt A",
361        )
362        .unwrap();
363        std::fs::write(dir.path().join("empty.md"), "---\ndescription: none\n---\n").unwrap();
364        std::fs::write(dir.path().join("notes.txt"), "ignored").unwrap();
365        let agents = load_project_agents(dir.path());
366        assert_eq!(agents.len(), 1);
367        assert_eq!(agents[0].name, "a");
368    }
369
370    #[test]
371    fn explorer_tools_are_read_only() {
372        assert!(explorer_tool("read_file"));
373        assert!(explorer_tool("grep"));
374        assert!(!explorer_tool("bash"));
375        assert!(!explorer_tool("write_file"));
376        assert!(!explorer_tool("explore"));
377    }
378}