1use 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;
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 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
109pub 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
260fn 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}