1use 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;
32const 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#[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
46pub 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
198fn 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}