1use 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;
33const 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#[derive(Debug, Clone, PartialEq, Eq)]
40pub struct ProjectAgent {
41 pub name: String,
42 pub description: String,
43 pub model: Option<String>,
44 pub tools: Vec<String>,
47 pub prompt: String,
48}
49
50impl ProjectAgent {
51 pub fn allows(&self, tool: &str) -> bool {
53 self.tools.is_empty() || self.tools.iter().any(|t| t == tool)
54 }
55}
56
57fn 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
83pub 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
90pub 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
245fn 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}