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