builtin.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452
  1. """Built-in tools: filesystem, shell, web, cron, spawn."""
  2. from __future__ import annotations
  3. import asyncio
  4. import difflib
  5. import html as html_mod
  6. import json
  7. import os
  8. import re
  9. from pathlib import Path
  10. from typing import TYPE_CHECKING, Any
  11. from urllib.parse import urlparse
  12. import httpx
  13. from toyclaw.tools.base import Tool
  14. if TYPE_CHECKING:
  15. from toyclaw.cron import CronService
  16. from toyclaw.subagent import SubagentManager
  17. # ---------------------------------------------------------------------------
  18. # Helpers
  19. # ---------------------------------------------------------------------------
  20. def _resolve(path: str, workspace: Path) -> Path:
  21. p = Path(path).expanduser()
  22. if not p.is_absolute():
  23. p = workspace / p
  24. return p.resolve()
  25. # ===================================================================
  26. # Filesystem tools
  27. # ===================================================================
  28. class ReadFileTool(Tool):
  29. name = "read_file"
  30. description = "Read the contents of a file."
  31. parameters = {
  32. "type": "object",
  33. "properties": {"path": {"type": "string", "description": "File path to read"}},
  34. "required": ["path"],
  35. }
  36. _MAX = 128_000
  37. def __init__(self, workspace: Path):
  38. self._ws = workspace
  39. async def execute(self, path: str, **kw: Any) -> str:
  40. try:
  41. fp = _resolve(path, self._ws)
  42. if not fp.exists():
  43. return f"Error: File not found: {path}"
  44. if not fp.is_file():
  45. return f"Error: Not a file: {path}"
  46. text = fp.read_text(encoding="utf-8")
  47. if len(text) > self._MAX:
  48. return text[: self._MAX] + f"\n... (truncated, {len(text)} chars total)"
  49. return text
  50. except Exception as exc:
  51. return f"Error reading file: {exc}"
  52. class WriteFileTool(Tool):
  53. name = "write_file"
  54. description = "Write content to a file. Creates parent directories if needed."
  55. parameters = {
  56. "type": "object",
  57. "properties": {
  58. "path": {"type": "string", "description": "File path"},
  59. "content": {"type": "string", "description": "Content to write"},
  60. },
  61. "required": ["path", "content"],
  62. }
  63. def __init__(self, workspace: Path):
  64. self._ws = workspace
  65. async def execute(self, path: str, content: str, **kw: Any) -> str:
  66. try:
  67. fp = _resolve(path, self._ws)
  68. fp.parent.mkdir(parents=True, exist_ok=True)
  69. fp.write_text(content, encoding="utf-8")
  70. return f"Wrote {len(content)} bytes to {fp}"
  71. except Exception as exc:
  72. return f"Error writing file: {exc}"
  73. class EditFileTool(Tool):
  74. name = "edit_file"
  75. description = "Edit a file by replacing old_text with new_text (must match exactly)."
  76. parameters = {
  77. "type": "object",
  78. "properties": {
  79. "path": {"type": "string", "description": "File path"},
  80. "old_text": {"type": "string", "description": "Exact text to find"},
  81. "new_text": {"type": "string", "description": "Replacement text"},
  82. },
  83. "required": ["path", "old_text", "new_text"],
  84. }
  85. def __init__(self, workspace: Path):
  86. self._ws = workspace
  87. async def execute(self, path: str, old_text: str, new_text: str, **kw: Any) -> str:
  88. try:
  89. fp = _resolve(path, self._ws)
  90. if not fp.exists():
  91. return f"Error: File not found: {path}"
  92. content = fp.read_text(encoding="utf-8")
  93. if old_text not in content:
  94. return self._hint(old_text, content, path)
  95. if content.count(old_text) > 1:
  96. return f"Error: old_text appears {content.count(old_text)} times; provide more context."
  97. fp.write_text(content.replace(old_text, new_text, 1), encoding="utf-8")
  98. return f"Edited {fp}"
  99. except Exception as exc:
  100. return f"Error editing file: {exc}"
  101. @staticmethod
  102. def _hint(old: str, content: str, path: str) -> str:
  103. lines, old_lines = content.splitlines(True), old.splitlines(True)
  104. best_ratio, best_i = 0.0, 0
  105. for i in range(max(1, len(lines) - len(old_lines) + 1)):
  106. r = difflib.SequenceMatcher(None, old_lines, lines[i : i + len(old_lines)]).ratio()
  107. if r > best_ratio:
  108. best_ratio, best_i = r, i
  109. if best_ratio > 0.5:
  110. diff = "\n".join(difflib.unified_diff(
  111. old_lines, lines[best_i : best_i + len(old_lines)],
  112. fromfile="old_text", tofile=f"{path} (line {best_i + 1})", lineterm="",
  113. ))
  114. return f"Error: old_text not found in {path}.\nBest match ({best_ratio:.0%}) at line {best_i + 1}:\n{diff}"
  115. return f"Error: old_text not found in {path}. No similar text found."
  116. class ListDirTool(Tool):
  117. name = "list_dir"
  118. description = "List directory contents."
  119. parameters = {
  120. "type": "object",
  121. "properties": {"path": {"type": "string", "description": "Directory path"}},
  122. "required": ["path"],
  123. }
  124. def __init__(self, workspace: Path):
  125. self._ws = workspace
  126. async def execute(self, path: str, **kw: Any) -> str:
  127. try:
  128. dp = _resolve(path, self._ws)
  129. if not dp.is_dir():
  130. return f"Error: Not a directory: {path}"
  131. items = sorted(dp.iterdir())
  132. if not items:
  133. return f"Directory {path} is empty"
  134. return "\n".join(
  135. f"{'📁' if i.is_dir() else '📄'} {i.name}" for i in items
  136. )
  137. except Exception as exc:
  138. return f"Error listing directory: {exc}"
  139. # ===================================================================
  140. # Shell
  141. # ===================================================================
  142. _DENY_PATTERNS = [
  143. r"\brm\s+-[rf]{1,2}\b",
  144. r"\bdel\s+/[fq]\b",
  145. r"\brmdir\s+/s\b",
  146. r"(?:^|[;&|]\s*)format\b",
  147. r"\b(mkfs|diskpart)\b",
  148. r"\bdd\s+if=",
  149. r">\s*/dev/sd",
  150. r"\b(shutdown|reboot|poweroff)\b",
  151. r":\(\)\s*\{.*\};\s*:",
  152. ]
  153. class ShellTool(Tool):
  154. name = "exec"
  155. description = "Execute a shell command and return its output."
  156. parameters = {
  157. "type": "object",
  158. "properties": {
  159. "command": {"type": "string", "description": "Shell command to execute"},
  160. },
  161. "required": ["command"],
  162. }
  163. def __init__(self, workspace: Path, timeout: int = 60):
  164. self._ws = workspace
  165. self._timeout = timeout
  166. async def execute(self, command: str, **kw: Any) -> str:
  167. lower = command.strip().lower()
  168. for pat in _DENY_PATTERNS:
  169. if re.search(pat, lower):
  170. return "Error: Command blocked by safety guard."
  171. try:
  172. proc = await asyncio.create_subprocess_shell(
  173. command,
  174. stdout=asyncio.subprocess.PIPE,
  175. stderr=asyncio.subprocess.PIPE,
  176. cwd=str(self._ws),
  177. )
  178. try:
  179. stdout, stderr = await asyncio.wait_for(proc.communicate(), self._timeout)
  180. except asyncio.TimeoutError:
  181. proc.kill()
  182. return f"Error: Command timed out after {self._timeout}s"
  183. parts: list[str] = []
  184. if stdout:
  185. parts.append(stdout.decode("utf-8", errors="replace"))
  186. if stderr and stderr.strip():
  187. parts.append(f"STDERR:\n{stderr.decode('utf-8', errors='replace')}")
  188. if proc.returncode:
  189. parts.append(f"\nExit code: {proc.returncode}")
  190. result = "\n".join(parts) or "(no output)"
  191. if len(result) > 10_000:
  192. result = result[:10_000] + "\n... (truncated)"
  193. return result
  194. except Exception as exc:
  195. return f"Error executing command: {exc}"
  196. # ===================================================================
  197. # Web
  198. # ===================================================================
  199. _UA = "Mozilla/5.0 (compatible; ToyClaw/0.1)"
  200. class WebSearchTool(Tool):
  201. name = "web_search"
  202. description = "Search the web via Brave Search API. Returns titles, URLs, snippets."
  203. parameters = {
  204. "type": "object",
  205. "properties": {
  206. "query": {"type": "string", "description": "Search query"},
  207. "count": {"type": "integer", "description": "Number of results (1-10)"},
  208. },
  209. "required": ["query"],
  210. }
  211. def __init__(self, api_key: str | None = None):
  212. self._key = api_key
  213. async def execute(self, query: str, count: int = 5, **kw: Any) -> str:
  214. key = self._key or os.environ.get("BRAVE_API_KEY", "")
  215. if not key:
  216. return "Error: Brave Search API key not configured."
  217. count = max(1, min(count, 10))
  218. try:
  219. async with httpx.AsyncClient(timeout=10) as c:
  220. r = await c.get(
  221. "https://api.search.brave.com/res/v1/web/search",
  222. params={"q": query, "count": count},
  223. headers={"Accept": "application/json", "X-Subscription-Token": key},
  224. )
  225. r.raise_for_status()
  226. results = r.json().get("web", {}).get("results", [])[:count]
  227. if not results:
  228. return f"No results for: {query}"
  229. lines = [f"Results for: {query}\n"]
  230. for i, item in enumerate(results, 1):
  231. lines.append(f"{i}. {item.get('title', '')}\n {item.get('url', '')}")
  232. if desc := item.get("description"):
  233. lines.append(f" {desc}")
  234. return "\n".join(lines)
  235. except Exception as exc:
  236. return f"Error: {exc}"
  237. class WebFetchTool(Tool):
  238. name = "web_fetch"
  239. description = "Fetch a URL and extract readable text content."
  240. parameters = {
  241. "type": "object",
  242. "properties": {
  243. "url": {"type": "string", "description": "URL to fetch"},
  244. },
  245. "required": ["url"],
  246. }
  247. _MAX = 50_000
  248. async def execute(self, url: str, **kw: Any) -> str:
  249. parsed = urlparse(url)
  250. if parsed.scheme not in ("http", "https"):
  251. return f"Error: Only http/https allowed, got '{parsed.scheme}'"
  252. try:
  253. from readability import Document
  254. async with httpx.AsyncClient(follow_redirects=True, timeout=30) as c:
  255. r = await c.get(url, headers={"User-Agent": _UA})
  256. r.raise_for_status()
  257. ctype = r.headers.get("content-type", "")
  258. if "application/json" in ctype:
  259. text = json.dumps(r.json(), indent=2, ensure_ascii=False)
  260. elif "text/html" in ctype or r.text[:256].lower().startswith(("<!doctype", "<html")):
  261. doc = Document(r.text)
  262. raw_html = doc.summary()
  263. text = f"# {doc.title()}\n\n{self._strip(raw_html)}" if doc.title() else self._strip(raw_html)
  264. else:
  265. text = r.text
  266. if len(text) > self._MAX:
  267. text = text[: self._MAX] + "\n... (truncated)"
  268. return text
  269. except Exception as exc:
  270. return f"Error fetching {url}: {exc}"
  271. @staticmethod
  272. def _strip(html: str) -> str:
  273. """Strip HTML tags and collapse whitespace."""
  274. text = re.sub(r"<script[\s\S]*?</script>", "", html, flags=re.I)
  275. text = re.sub(r"<style[\s\S]*?</style>", "", text, flags=re.I)
  276. text = re.sub(r"<[^>]+>", "", text)
  277. text = html_mod.unescape(text)
  278. return re.sub(r"\n{3,}", "\n\n", text).strip()
  279. # ===================================================================
  280. # Cron tool (interface to CronService)
  281. # ===================================================================
  282. class CronTool(Tool):
  283. name = "cron"
  284. description = "Schedule reminders and recurring tasks. Actions: add, list, remove."
  285. parameters = {
  286. "type": "object",
  287. "properties": {
  288. "action": {
  289. "type": "string",
  290. "enum": ["add", "list", "remove"],
  291. "description": "Action to perform",
  292. },
  293. "message": {"type": "string", "description": "Reminder message (for add)"},
  294. "every_seconds": {"type": "integer", "description": "Interval in seconds (recurring)"},
  295. "cron_expr": {"type": "string", "description": "Cron expression, e.g. '0 9 * * *'"},
  296. "at": {"type": "string", "description": "ISO datetime for one-time, e.g. '2026-03-10T10:30:00'"},
  297. "job_id": {"type": "string", "description": "Job ID (for remove)"},
  298. },
  299. "required": ["action"],
  300. }
  301. def __init__(self, service: CronService):
  302. self._svc = service
  303. self._channel = "cli"
  304. self._chat_id = "direct"
  305. def set_context(self, channel: str, chat_id: str) -> None:
  306. self._channel = channel
  307. self._chat_id = chat_id
  308. async def execute(self, action: str, **kw: Any) -> str:
  309. if action == "add":
  310. return self._add(**kw)
  311. if action == "list":
  312. return self._list()
  313. if action == "remove":
  314. return self._remove(kw.get("job_id"))
  315. return f"Unknown action: {action}"
  316. def _add(
  317. self,
  318. message: str = "",
  319. every_seconds: int | None = None,
  320. cron_expr: str | None = None,
  321. at: str | None = None,
  322. **_: Any,
  323. ) -> str:
  324. if not message:
  325. return "Error: message is required"
  326. from toyclaw.cron import CronSchedule
  327. delete_after = False
  328. if every_seconds:
  329. sched = CronSchedule(kind="every", every_ms=every_seconds * 1000)
  330. elif cron_expr:
  331. sched = CronSchedule(kind="cron", expr=cron_expr)
  332. elif at:
  333. from datetime import datetime
  334. try:
  335. dt = datetime.fromisoformat(at)
  336. except ValueError:
  337. return f"Error: invalid datetime '{at}'"
  338. sched = CronSchedule(kind="at", at_ms=int(dt.timestamp() * 1000))
  339. delete_after = True
  340. else:
  341. return "Error: provide every_seconds, cron_expr, or at"
  342. job = self._svc.add_job(
  343. name=message[:30],
  344. schedule=sched,
  345. message=message,
  346. channel=self._channel,
  347. chat_id=self._chat_id,
  348. delete_after_run=delete_after,
  349. )
  350. return f"Created job '{job.name}' (id: {job.id})"
  351. def _list(self) -> str:
  352. jobs = self._svc.list_jobs()
  353. if not jobs:
  354. return "No scheduled jobs."
  355. return "Scheduled jobs:\n" + "\n".join(
  356. f"- {j.name} (id: {j.id}, {j.schedule.kind})" for j in jobs
  357. )
  358. def _remove(self, job_id: str | None) -> str:
  359. if not job_id:
  360. return "Error: job_id is required"
  361. return f"Removed job {job_id}" if self._svc.remove_job(job_id) else f"Job {job_id} not found"
  362. # ===================================================================
  363. # Spawn tool (interface to SubagentManager)
  364. # ===================================================================
  365. class SpawnTool(Tool):
  366. name = "spawn"
  367. description = (
  368. "Spawn a background sub-agent for a complex or time-consuming task. "
  369. "The sub-agent will complete the task independently and report back."
  370. )
  371. parameters = {
  372. "type": "object",
  373. "properties": {
  374. "task": {"type": "string", "description": "Task description for the sub-agent"},
  375. "label": {"type": "string", "description": "Short label (for display)"},
  376. },
  377. "required": ["task"],
  378. }
  379. def __init__(self, manager: SubagentManager):
  380. self._mgr = manager
  381. self._channel = "cli"
  382. self._chat_id = "direct"
  383. def set_context(self, channel: str, chat_id: str) -> None:
  384. self._channel = channel
  385. self._chat_id = chat_id
  386. async def execute(self, task: str, label: str | None = None, **kw: Any) -> str:
  387. return await self._mgr.spawn(
  388. task=task,
  389. label=label,
  390. origin_channel=self._channel,
  391. origin_chat_id=self._chat_id,
  392. )