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` and `tools`; the body is the system prompt), selected with
13//! `agent` here and in `sessions_spawn`.
14
15use std::path::Path;
16use std::sync::Arc;
17
18use async_trait::async_trait;
19use serde_json::json;
20
21use super::{schema_object, Tool, ToolRegistry, ToolResult};
22use crate::config::Config;
23use crate::internal::storage::db::Database;
24use crate::internal::tool_runtime::runtime::{
25    auth_context_from_input, tool_concurrency_class, ToolAuthContext, ToolConcurrencyClass,
26};
27use microclaw_core::llm_types::{
28    ContentBlock, Message, MessageContent, ResponseContentBlock, ToolDefinition,
29};
30
31const MAX_ITERATIONS: usize = 30;
32const MAX_REPORT_CHARS: usize = 16_000;
33/// Tool output kept per call inside the explore loop.
34const MAX_TOOL_OUTPUT_CHARS: usize = 24_000;
35
36const 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.";
37
38/// A project-defined helper agent.
39#[derive(Debug, Clone, PartialEq, Eq)]
40pub struct ProjectAgent {
41    pub name: String,
42    pub description: String,
43    pub model: Option<String>,
44    /// Tools the agent may use (`tools:` in the front matter); empty means
45    /// the caller's usual set. It can only narrow that set.
46    pub tools: Vec<String>,
47    pub prompt: String,
48}
49
50impl ProjectAgent {
51    /// Whether the agent may use `tool` (always true without a `tools` list).
52    pub fn allows(&self, tool: &str) -> bool {
53        self.tools.is_empty() || self.tools.iter().any(|t| t == tool)
54    }
55}
56
57/// Front-matter tool names to engine tool names (`read` → `read_file`).
58fn tool_names(spec: &str) -> Vec<String> {
59    let spec = spec.trim().trim_start_matches('[').trim_end_matches(']');
60    let mut tools = Vec::new();
61    for raw in spec.split(',') {
62        let name = raw.trim().trim_matches(['"', '\'']).to_ascii_lowercase();
63        let mapped: &[&str] = match name.as_str() {
64            "" => &[],
65            "read" => &["read_file"],
66            "write" => &["write_file"],
67            "edit" => &["edit_file", "apply_patch"],
68            "shell" | "bash" => &["bash", "bash_output", "bash_input", "bash_kill"],
69            "web" => &["web_fetch", "web_search"],
70            "search" => &["grep", "glob"],
71            other => {
72                tools.push(other.to_string());
73                continue;
74            }
75        };
76        tools.extend(mapped.iter().map(|s| s.to_string()));
77    }
78    tools.sort();
79    tools.dedup();
80    tools
81}
82
83/// Find a project agent by name in `dir`.
84pub fn find_project_agent(dir: Option<&str>, name: &str) -> Option<ProjectAgent> {
85    load_project_agents(Path::new(dir?))
86        .into_iter()
87        .find(|agent| agent.name == name)
88}
89
90/// The project agents and those of `extra_agents_dirs` (plugins); the first
91/// definition of a name wins.
92pub fn config_agents(config: &Config) -> Vec<ProjectAgent> {
93    let mut agents: Vec<ProjectAgent> = Vec::new();
94    for dir in config
95        .project_agents_dir
96        .iter()
97        .chain(config.extra_agents_dirs.iter())
98    {
99        for agent in load_project_agents(Path::new(dir)) {
100            if !agents.iter().any(|a| a.name == agent.name) {
101                agents.push(agent);
102            }
103        }
104    }
105    agents.sort_by(|a, b| a.name.cmp(&b.name));
106    agents
107}
108
109/// Agents defined in `dir` (`<name>.md` with optional front matter).
110pub fn load_project_agents(dir: &Path) -> Vec<ProjectAgent> {
111    let Ok(entries) = std::fs::read_dir(dir) else {
112        return Vec::new();
113    };
114    let mut agents: Vec<ProjectAgent> = entries
115        .filter_map(|entry| entry.ok())
116        .map(|entry| entry.path())
117        .filter(|path| path.extension().is_some_and(|ext| ext == "md"))
118        .filter_map(|path| {
119            let name = path.file_stem()?.to_str()?.to_string();
120            let text = std::fs::read_to_string(&path).ok()?;
121            Some(parse_agent(&name, &text))
122        })
123        .filter(|agent| !agent.prompt.trim().is_empty())
124        .collect();
125    agents.sort_by(|a, b| a.name.cmp(&b.name));
126    agents
127}
128
129fn parse_agent(name: &str, text: &str) -> ProjectAgent {
130    let mut description = String::new();
131    let mut model = None;
132    let mut tools = Vec::new();
133    let mut body = text;
134    if let Some(rest) = text.strip_prefix("---") {
135        if let Some(end) = rest.find("\n---") {
136            for line in rest[..end].lines() {
137                if let Some((key, value)) = line.split_once(':') {
138                    let value = value.trim().trim_matches('"').to_string();
139                    match key.trim() {
140                        "description" => description = value,
141                        "model" if !value.is_empty() => model = Some(value),
142                        "tools" => tools = tool_names(&value),
143                        _ => {}
144                    }
145                }
146            }
147            body = rest[end + 4..].trim_start_matches(['\r', '\n']);
148        }
149    }
150    ProjectAgent {
151        name: name.to_string(),
152        description,
153        model,
154        tools,
155        prompt: body.trim().to_string(),
156    }
157}
158
159pub struct ExploreTool {
160    config: Config,
161    db: Arc<Database>,
162    agents: Vec<ProjectAgent>,
163}
164
165impl ExploreTool {
166    pub fn new(config: &Config, db: Arc<Database>) -> Self {
167        let agents = config_agents(config);
168        Self {
169            config: config.clone(),
170            db,
171            agents,
172        }
173    }
174}
175
176fn truncate(text: &str, max: usize) -> String {
177    crate::context_window::truncate_chars(text, max)
178}
179
180#[async_trait]
181impl Tool for ExploreTool {
182    fn name(&self) -> &str {
183        "explore"
184    }
185
186    fn definition(&self) -> ToolDefinition {
187        let mut description = String::from(
188            "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.",
189        );
190        if !self.agents.is_empty() {
191            description.push_str(" Project agents (pass as `agent`): ");
192            let list: Vec<String> = self
193                .agents
194                .iter()
195                .map(|a| {
196                    if a.description.is_empty() {
197                        a.name.clone()
198                    } else {
199                        format!("{} ({})", a.name, a.description)
200                    }
201                })
202                .collect();
203            description.push_str(&list.join("; "));
204            description.push('.');
205        }
206        let mut properties = json!({
207            "task": {
208                "type": "string",
209                "description": "The question to answer, with any paths or names you already know"
210            }
211        });
212        if !self.agents.is_empty() {
213            properties["agent"] = json!({
214                "type": "string",
215                "enum": self.agents.iter().map(|a| a.name.clone()).collect::<Vec<_>>(),
216                "description": "Project agent to use instead of the default explorer"
217            });
218        }
219        ToolDefinition {
220            name: "explore".into(),
221            description,
222            input_schema: schema_object(properties, &["task"]),
223        }
224    }
225
226    async fn execute(&self, input: serde_json::Value) -> ToolResult {
227        let Some(task) = input
228            .get("task")
229            .and_then(|v| v.as_str())
230            .map(str::trim)
231            .filter(|t| !t.is_empty())
232        else {
233            return ToolResult::error("explore: `task` is required".into());
234        };
235        let agent = match input.get("agent").and_then(|v| v.as_str()) {
236            Some(name) => match self.agents.iter().find(|a| a.name == name) {
237                Some(agent) => Some(agent.clone()),
238                None => return ToolResult::error(format!("explore: unknown agent `{name}`")),
239            },
240            None => None,
241        };
242        let parent = auth_context_from_input(&input);
243        let auth = ToolAuthContext {
244            caller_channel: parent
245                .as_ref()
246                .map(|a| a.caller_channel.clone())
247                .unwrap_or_else(|| "code".into()),
248            caller_chat_id: parent.as_ref().map(|a| a.caller_chat_id).unwrap_or(0),
249            principal: "subagent:explore".into(),
250            control_chat_ids: Vec::new(),
251            env_files: Vec::new(),
252        };
253        match run_explore(&self.config, self.db.clone(), &auth, task, agent.as_ref()).await {
254            Ok(report) => ToolResult::success(report),
255            Err(e) => ToolResult::error(format!("explore failed: {e}")),
256        }
257    }
258}
259
260/// Read-only tools the explorer may use.
261fn explorer_tool(name: &str) -> bool {
262    tool_concurrency_class(name) == ToolConcurrencyClass::ReadOnly
263        && matches!(
264            name,
265            "read_file" | "grep" | "glob" | "web_fetch" | "web_search" | "fetch_artifact"
266        )
267}
268
269async fn run_explore(
270    config: &Config,
271    db: Arc<Database>,
272    auth: &ToolAuthContext,
273    task: &str,
274    agent: Option<&ProjectAgent>,
275) -> anyhow::Result<String> {
276    let tools = ToolRegistry::new_sub_agent(config, db.clone(), None, false);
277    let tool_defs: Vec<ToolDefinition> = tools
278        .definitions_for(auth)
279        .into_iter()
280        .filter(|d| explorer_tool(&d.name))
281        .filter(|d| agent.is_none_or(|a| a.allows(&d.name)))
282        .collect();
283    let llm = crate::llm::create_provider(config);
284    let model = agent
285        .and_then(|a| a.model.clone())
286        .unwrap_or_else(|| config.aux_models.subagent_model(&config.model).to_string());
287    let system = match agent {
288        Some(agent) => format!(
289            "{}\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.",
290            agent.prompt
291        ),
292        None => DEFAULT_PROMPT.to_string(),
293    };
294    let mut messages = vec![Message {
295        role: "user".into(),
296        content: MessageContent::Text(task.to_string()),
297    }];
298    let mut files_read = 0usize;
299    for _ in 0..MAX_ITERATIONS {
300        let response = llm
301            .send_message_with_model(
302                &system,
303                messages.clone(),
304                Some(tool_defs.clone()),
305                Some(&model),
306            )
307            .await?;
308        if let Some(usage) = &response.usage {
309            let (channel, provider, model_name) = (
310                auth.caller_channel.clone(),
311                config.llm_provider.clone(),
312                model.clone(),
313            );
314            let (chat_id, input_tokens, output_tokens) = (
315                auth.caller_chat_id,
316                i64::from(usage.input_tokens),
317                i64::from(usage.output_tokens),
318            );
319            let _ = crate::internal::storage::db::call_blocking(db.clone(), move |db| {
320                db.log_llm_usage(
321                    chat_id,
322                    &channel,
323                    &provider,
324                    &model_name,
325                    input_tokens,
326                    output_tokens,
327                    "explore",
328                )
329                .map(|_| ())
330            })
331            .await;
332        }
333        let mut text = String::new();
334        let mut calls = Vec::new();
335        for block in &response.content {
336            match block {
337                ResponseContentBlock::Text { text: t } => text.push_str(t),
338                ResponseContentBlock::ToolUse {
339                    id, name, input, ..
340                } => calls.push((id.clone(), name.clone(), input.clone())),
341                _ => {}
342            }
343        }
344        if calls.is_empty() {
345            let report = if text.trim().is_empty() {
346                "(the explorer found nothing to report)".to_string()
347            } else {
348                truncate(text.trim(), MAX_REPORT_CHARS)
349            };
350            return Ok(format!("{report}\n\n[explore: {files_read} tool calls]"));
351        }
352        let mut assistant_blocks = Vec::new();
353        if !text.trim().is_empty() {
354            assistant_blocks.push(ContentBlock::Text { text: text.clone() });
355        }
356        for (id, name, input) in &calls {
357            assistant_blocks.push(ContentBlock::ToolUse {
358                id: id.clone(),
359                name: name.clone(),
360                input: input.clone(),
361                thought_signature: None,
362            });
363        }
364        messages.push(Message {
365            role: "assistant".into(),
366            content: MessageContent::Blocks(assistant_blocks),
367        });
368        let results = futures_util::future::join_all(calls.iter().map(|(_, name, input)| {
369            let name = name.clone();
370            let input = input.clone();
371            let tools = &tools;
372            async move {
373                if !explorer_tool(&name) {
374                    return ToolResult::error(format!(
375                        "`{name}` is not available to the explorer (read-only tools only)"
376                    ));
377                }
378                if agent.is_some_and(|a| !a.allows(&name)) {
379                    return ToolResult::error(format!(
380                        "`{name}` is not in this agent's `tools` list"
381                    ));
382                }
383                tools.execute_with_auth(&name, input, auth).await
384            }
385        }))
386        .await;
387        files_read += calls.len();
388        let result_blocks = calls
389            .iter()
390            .zip(results)
391            .map(|((id, _, _), result)| ContentBlock::ToolResult {
392                tool_use_id: id.clone(),
393                content: truncate(&result.content, MAX_TOOL_OUTPUT_CHARS),
394                is_error: result.is_error.then_some(true),
395            })
396            .collect();
397        messages.push(Message {
398            role: "user".into(),
399            content: MessageContent::Blocks(result_blocks),
400        });
401    }
402    anyhow::bail!("no report after {MAX_ITERATIONS} steps; ask a narrower question")
403}
404
405#[cfg(test)]
406mod tests {
407    use super::*;
408
409    #[test]
410    fn parses_agent_front_matter() {
411        let agent = parse_agent(
412            "db-expert",
413            "---\ndescription: Knows the storage layer\nmodel: small-model\n---\nYou explain the database code.\n",
414        );
415        assert_eq!(agent.description, "Knows the storage layer");
416        assert_eq!(agent.model.as_deref(), Some("small-model"));
417        assert_eq!(agent.prompt, "You explain the database code.");
418        let plain = parse_agent("plain", "Just a prompt.");
419        assert_eq!(plain.prompt, "Just a prompt.");
420        assert!(plain.description.is_empty());
421    }
422
423    #[test]
424    fn loads_agents_from_a_directory() {
425        let dir = tempfile::tempdir().unwrap();
426        std::fs::write(
427            dir.path().join("a.md"),
428            "---\ndescription: A\n---\nPrompt A",
429        )
430        .unwrap();
431        std::fs::write(dir.path().join("empty.md"), "---\ndescription: none\n---\n").unwrap();
432        std::fs::write(dir.path().join("notes.txt"), "ignored").unwrap();
433        let agents = load_project_agents(dir.path());
434        assert_eq!(agents.len(), 1);
435        assert_eq!(agents[0].name, "a");
436    }
437
438    #[test]
439    fn agent_tools_narrow_the_tool_set_and_accept_short_names() {
440        let agent = parse_agent(
441            "reviewer",
442            "---\ndescription: Reviews\ntools: [read, grep, \"web\"]\n---\nReview the code.\n",
443        );
444        assert_eq!(
445            agent.tools,
446            vec!["grep", "read_file", "web_fetch", "web_search"]
447        );
448        assert!(agent.allows("read_file"));
449        assert!(!agent.allows("bash"));
450        let all = parse_agent("all", "Do anything.");
451        assert!(all.tools.is_empty());
452        assert!(all.allows("bash"));
453        assert_eq!(
454            tool_names("shell, edit"),
455            vec![
456                "apply_patch",
457                "bash",
458                "bash_input",
459                "bash_kill",
460                "bash_output",
461                "edit_file"
462            ]
463        );
464        let dir = tempfile::tempdir().unwrap();
465        std::fs::write(
466            dir.path().join("reviewer.md"),
467            "---\ntools: read\n---\nReview.",
468        )
469        .unwrap();
470        let found = find_project_agent(dir.path().to_str(), "reviewer").unwrap();
471        assert_eq!(found.tools, vec!["read_file"]);
472        assert!(find_project_agent(dir.path().to_str(), "missing").is_none());
473        assert!(find_project_agent(None, "reviewer").is_none());
474    }
475
476    #[test]
477    fn plugin_agent_dirs_follow_the_project_dir() {
478        let project = tempfile::tempdir().unwrap();
479        let plugin = tempfile::tempdir().unwrap();
480        std::fs::write(project.path().join("reviewer.md"), "Project reviewer.").unwrap();
481        std::fs::write(plugin.path().join("reviewer.md"), "Plugin reviewer.").unwrap();
482        std::fs::write(plugin.path().join("tester.md"), "Plugin tester.").unwrap();
483        let mut config = Config::test_defaults();
484        config.project_agents_dir = Some(project.path().to_string_lossy().into_owned());
485        config.extra_agents_dirs = vec![plugin.path().to_string_lossy().into_owned()];
486        let agents = config_agents(&config);
487        let names: Vec<&str> = agents.iter().map(|a| a.name.as_str()).collect();
488        assert_eq!(names, ["reviewer", "tester"]);
489        assert_eq!(agents[0].prompt.trim(), "Project reviewer.");
490        config.project_agents_dir = None;
491        assert_eq!(config_agents(&config).len(), 2);
492    }
493
494    #[test]
495    fn explorer_tools_are_read_only() {
496        assert!(explorer_tool("read_file"));
497        assert!(explorer_tool("grep"));
498        assert!(!explorer_tool("bash"));
499        assert!(!explorer_tool("write_file"));
500        assert!(!explorer_tool("explore"));
501    }
502}