traceforge-pcb 1.0.0__py3-none-any.whl

traceforge/tools/files.py

@@ -0,0 +1,777 @@
+"""Filesystem and shell tools, confined to the workspace."""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import difflib
+import os
+import re
+import shutil
+import subprocess
+import time
+from pathlib import Path
+from typing import Any
+
+from traceforge.kicad.project import SKIP_DIRS
+from traceforge.tools.base import Tool, ToolContext, ToolError, ToolKind, ToolOutput
+from traceforge.tools.processes import start_background
+
+MAX_READ_LINES = 2000
+MAX_READ_CHARS = 28_000  # one read stays well inside the context budget
+MAX_LINE = 2000
+MAX_FILE_BYTES = 25 * 1024 * 1024
+MAX_LS = 1000
+
+
+def _iter_files(root: Path, limit: int = 20_000):
+    count = 0
+    for directory, dirnames, filenames in os.walk(root):
+        dirnames[:] = sorted(d for d in dirnames if d not in SKIP_DIRS and not d.startswith("."))
+        for filename in sorted(filenames):
+            yield Path(directory) / filename
+            count += 1
+            if count >= limit:
+                return
+
+
+def ls(args: dict[str, Any], ctx: ToolContext) -> str:
+    path = ctx.resolve(args.get("path"), must_exist=True)
+    if path.is_file():
+        return f"{ctx.display(path)} ({path.stat().st_size} bytes)"
+    lines = []
+    entries = sorted(path.iterdir(), key=lambda p: (not p.is_dir(), p.name.lower()))
+    for entry in entries:
+        if entry.name in SKIP_DIRS and path == ctx.workspace:
+            continue
+        if entry.is_dir():
+            lines.append(f"{entry.name}/")
+        else:
+            lines.append(f"{entry.name}  ({entry.stat().st_size} bytes)")
+        if len(lines) >= MAX_LS:
+            lines.append(f"... ({len(entries) - MAX_LS} more entries; use glob to narrow)")
+            break
+    return "\n".join(lines) or "(empty directory)"
+
+
+# ------------------------------------------------------------------------------ read
+
+IMAGE_TYPES = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+}
+MAX_IMAGE_BYTES = 3_700_000  # base64 stays under the 5 MB per-image API limit
+MAX_PDF_PAGES = 20
+
+
+def _convert_available() -> str | None:
+    return shutil.which("magick") or shutil.which("convert")
+
+
+def _image_output(path: Path, ctx: ToolContext, data: bytes | None = None) -> ToolOutput:
+    media = IMAGE_TYPES.get(path.suffix.lower(), "image/png")
+    data = path.read_bytes() if data is None else data
+    note = ""
+    if len(data) > MAX_IMAGE_BYTES:
+        tool = _convert_available()
+        if tool is None:
+            raise ToolError(
+                f"image is {len(data)} bytes, over the {MAX_IMAGE_BYTES}-byte limit, and "
+                "ImageMagick is not installed to shrink it"
+            )
+        shrunk = subprocess.run(
+            [tool, str(path), "-resize", "1568x1568>", "-quality", "85", "jpeg:-"],
+            capture_output=True,
+            timeout=60,
+            check=False,
+        )
+        if shrunk.returncode != 0 or len(shrunk.stdout) > MAX_IMAGE_BYTES:
+            raise ToolError("image is too large to show and could not be shrunk")
+        data, media, note = shrunk.stdout, "image/jpeg", " (downscaled)"
+    encoded = base64.b64encode(data).decode("ascii")
+    return ToolOutput(
+        f"{ctx.display(path)}: {media}, {path.stat().st_size} bytes{note}",
+        [{"media_type": media, "data": encoded}],
+    )
+
+
+def _svg_as_image(path: Path, ctx: ToolContext) -> ToolOutput:
+    tool = _convert_available()
+    if tool is None:
+        raise ToolError("rendering SVG needs ImageMagick (convert); read it as text instead")
+    done = subprocess.run(
+        [
+            tool,
+            "-density",
+            "150",
+            "-background",
+            "white",
+            "-flatten",
+            str(path),
+            "-resize",
+            "1568x1568>",
+            "png:-",
+        ],
+        capture_output=True,
+        timeout=120,
+        check=False,
+    )
+    if done.returncode != 0 or not done.stdout:
+        raise ToolError(f"could not render {ctx.display(path)}: {done.stderr.decode()[:300]}")
+    return _image_output(path.with_suffix(".png"), ctx, done.stdout)
+
+
+def _pdf_text(path: Path, pages: str | None) -> str:
+    if shutil.which("pdftotext") is None:
+        raise ToolError("reading PDFs needs pdftotext (poppler-utils)")
+    first, last = 1, MAX_PDF_PAGES
+    if pages:
+        match = re.fullmatch(r"\s*(\d+)\s*(?:-\s*(\d+))?\s*", str(pages))
+        if not match:
+            raise ToolError("pages must look like '3' or '1-5'")
+        first = int(match.group(1))
+        last = int(match.group(2) or first)
+        if last < first:
+            raise ToolError("pages: the last page is before the first")
+        if last - first + 1 > MAX_PDF_PAGES:
+            raise ToolError(f"at most {MAX_PDF_PAGES} pages per read")
+    done = subprocess.run(
+        ["pdftotext", "-layout", "-f", str(first), "-l", str(last), str(path), "-"],
+        capture_output=True,
+        timeout=120,
+        check=False,
+    )
+    if done.returncode != 0:
+        raise ToolError(f"pdftotext failed: {done.stderr.decode(errors='replace')[:300]}")
+    text = done.stdout.decode("utf-8", errors="replace")
+    pages_read = text.count("\f") or 1
+    return f"[pages {first}-{first + pages_read - 1}]\n" + text.replace("\f", "\n[page break]\n")
+
+
+def read_file(args: dict[str, Any], ctx: ToolContext) -> str | ToolOutput:
+    path = ctx.resolve(args["path"], must_exist=True)
+    if path.is_dir():
+        raise ToolError(f"{args['path']} is a directory; use ls")
+    suffix = path.suffix.lower()
+    if suffix in IMAGE_TYPES:
+        return _image_output(path, ctx)
+    if suffix == ".svg" and args.get("as_image"):
+        return _svg_as_image(path, ctx)
+    if path.stat().st_size > MAX_FILE_BYTES:
+        raise ToolError("file is too large to read; use grep to find the relevant part")
+    if suffix == ".pdf":
+        text = _pdf_text(path, args.get("pages"))
+    else:
+        data = path.read_bytes()
+        if b"\x00" in data[:8192]:
+            raise ToolError(
+                f"binary file ({len(data)} bytes); not shown. Images (png, jpg, gif, webp) and "
+                "PDFs can be read; inspect other formats with a command"
+            )
+        text = data.decode("utf-8", errors="replace")
+    track_read(ctx, path)
+    lines = text.splitlines()
+    if not lines:
+        return "(empty file)"
+    offset = max(1, int(args.get("offset") or 1))
+    if offset > len(lines):
+        raise ToolError(f"offset {offset} is past the end of the file ({len(lines)} lines)")
+    limit = min(max(int(args.get("limit") or MAX_READ_LINES), 1), MAX_READ_LINES)
+    width = len(str(min(offset + limit, len(lines))))
+    out: list[str] = []
+    used = 0
+    clipped = 0
+    for number in range(offset, min(offset + limit, len(lines) + 1)):
+        line = lines[number - 1]
+        if len(line) > MAX_LINE:
+            line = line[:MAX_LINE] + f" ... [line clipped, {len(line)} chars]"
+            clipped += 1
+        entry = f"{str(number).rjust(width)}\t{line}"
+        if out and used + len(entry) > MAX_READ_CHARS:
+            break
+        out.append(entry)
+        used += len(entry) + 1
+    last = offset + len(out) - 1
+    header = f"[{ctx.display(path)}: lines {offset}-{last} of {len(lines)}]"
+    body = header + "\n" + "\n".join(out)
+    if last < len(lines):
+        body += f"\n... ({len(lines) - last} more lines; continue with offset={last + 1})"
+    return body
+
+
+def track_read(ctx: ToolContext, path: Path) -> None:
+    ctx.state.setdefault("files_read", set()).add(str(path))
+
+
+# ----------------------------------------------------------------------------- write
+
+MAX_DIFF_LINES = 60
+
+
+def diff_preview(before: str, after: str, name: str) -> str:
+    """A short unified diff of a change, for the tool result and approval prompts."""
+    lines = list(
+        difflib.unified_diff(
+            before.splitlines(), after.splitlines(), f"a/{name}", f"b/{name}", n=2, lineterm=""
+        )
+    )
+    if not lines:
+        return "(no textual change)"
+    added = sum(1 for x in lines if x.startswith("+") and not x.startswith("+++"))
+    removed = sum(1 for x in lines if x.startswith("-") and not x.startswith("---"))
+    shown = [x[:300] for x in lines[:MAX_DIFF_LINES]]
+    if len(lines) > MAX_DIFF_LINES:
+        shown.append(f"... ({len(lines) - MAX_DIFF_LINES} more diff lines)")
+    return f"+{added} -{removed}\n" + "\n".join(shown)
+
+
+def write_file(args: dict[str, Any], ctx: ToolContext) -> str:
+    path = ctx.resolve(args["path"], for_write=True)
+    if path.is_dir():
+        raise ToolError(f"{args['path']} is a directory")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existed = path.exists()
+    before = path.read_text(encoding="utf-8", errors="replace") if existed else ""
+    path.write_text(args["content"], encoding="utf-8")
+    track_read(ctx, path)
+    if not existed:
+        lines = args["content"].count("\n") + (0 if args["content"].endswith("\n") else 1)
+        return f"created {ctx.display(path)} ({len(args['content'])} chars, {lines} lines)"
+    return f"updated {ctx.display(path)} ({len(args['content'])} chars)\n" + diff_preview(
+        before, args["content"], ctx.display(path)
+    )
+
+
+def _apply_edit(
+    text: str, old: str, new: str, replace_all: bool, label: str = ""
+) -> tuple[str, int]:
+    if old == new:
+        raise ToolError(f"{label}old_string and new_string are identical")
+    if old == "":
+        raise ToolError(f"{label}old_string is empty; use write_file to create a file")
+    count = text.count(old)
+    if count == 0:
+        raise ToolError(
+            f"{label}old_string not found; read the file again and copy the text exactly"
+        )
+    if count > 1 and not replace_all:
+        raise ToolError(
+            f"{label}old_string occurs {count} times; add context to make it unique or set "
+            "replace_all"
+        )
+    if replace_all:
+        return text.replace(old, new), count
+    return text.replace(old, new, 1), 1
+
+
+def edit_file(args: dict[str, Any], ctx: ToolContext) -> str:
+    path = ctx.resolve(args["path"], must_exist=True, for_write=True)
+    text = path.read_text(encoding="utf-8")
+    updated, count = _apply_edit(
+        text, args["old_string"], args["new_string"], bool(args.get("replace_all"))
+    )
+    path.write_text(updated, encoding="utf-8")
+    track_read(ctx, path)
+    return f"edited {ctx.display(path)} ({count} replacement(s))\n" + diff_preview(
+        text, updated, ctx.display(path)
+    )
+
+
+def multi_edit(args: dict[str, Any], ctx: ToolContext) -> str:
+    path = ctx.resolve(args["path"], must_exist=True, for_write=True)
+    edits = args["edits"]
+    if not edits:
+        raise ToolError("edits is empty")
+    text = path.read_text(encoding="utf-8")
+    updated, total = text, 0
+    for index, edit in enumerate(edits, start=1):
+        if not isinstance(edit, dict) or "old_string" not in edit or "new_string" not in edit:
+            raise ToolError(f"edit {index}: needs old_string and new_string")
+        updated, count = _apply_edit(
+            updated,
+            str(edit["old_string"]),
+            str(edit["new_string"]),
+            bool(edit.get("replace_all")),
+            f"edit {index}: ",
+        )
+        total += count
+    # All edits applied in memory; only now does the file change (all or nothing).
+    path.write_text(updated, encoding="utf-8")
+    track_read(ctx, path)
+    return (
+        f"edited {ctx.display(path)} ({len(edits)} edits, {total} replacement(s))\n"
+        + diff_preview(text, updated, ctx.display(path))
+    )
+
+
+def delete_file(args: dict[str, Any], ctx: ToolContext) -> str:
+    path = ctx.resolve(args["path"], must_exist=True, for_write=True)
+    if path == ctx.workspace or (ctx.scratch is not None and path == ctx.scratch.resolve()):
+        raise ToolError("refusing to delete the workspace or scratch root")
+    if path.is_dir():
+        if not args.get("recursive"):
+            raise ToolError(f"{args['path']} is a directory; set recursive=true to delete it")
+        count = sum(1 for _ in path.rglob("*"))
+        shutil.rmtree(path)
+        return f"deleted directory {ctx.display(path)} ({count} entries)"
+    size = path.stat().st_size
+    path.unlink()
+    return f"deleted {ctx.display(path)} ({size} bytes)"
+
+
+def write_binary_file(args: dict[str, Any], ctx: ToolContext) -> str:
+    path = ctx.resolve(args["path"], for_write=True)
+    try:
+        data = base64.b64decode("".join(str(args["data"]).split()), validate=True)
+    except ValueError as exc:
+        raise ToolError(f"data is not valid base64: {exc}") from exc
+    if len(data) > MAX_FILE_BYTES:
+        raise ToolError("file is too large")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    existed = path.exists()
+    path.write_bytes(data)
+    return f"{'updated' if existed else 'created'} {ctx.display(path)} ({len(data)} bytes)"
+
+
+# ---------------------------------------------------------------------------- search
+
+MAX_GLOB = 500
+SEARCH_SECONDS = 20.0
+
+
+def glob_regex(pattern: str) -> re.Pattern[str]:
+    """Translate a glob with ``**``, ``*``, ``?``, ``[..]`` and ``{a,b}`` to a regex."""
+    out, i = [], 0
+    while i < len(pattern):
+        char = pattern[i]
+        if pattern.startswith("**/", i):
+            out.append("(?:.*/)?")
+            i += 3
+            continue
+        if pattern.startswith("**", i):
+            out.append(".*")
+            i += 2
+            continue
+        if char == "*":
+            out.append("[^/]*")
+        elif char == "?":
+            out.append("[^/]")
+        elif char == "[":
+            close = pattern.find("]", i + 1)
+            if close == -1:
+                out.append(re.escape(char))
+            else:
+                body = pattern[i + 1 : close].replace("\\", "\\\\")
+                if body.startswith("!"):
+                    body = "^" + body[1:]
+                out.append(f"[{body}]")
+                i = close
+        elif char == "{":
+            close = pattern.find("}", i + 1)
+            if close == -1:
+                out.append(re.escape(char))
+            else:
+                options = pattern[i + 1 : close].split(",")
+                out.append("(?:" + "|".join(glob_regex(o).pattern[:-2] for o in options) + ")")
+                i = close
+        else:
+            out.append(re.escape(char))
+        i += 1
+    return re.compile("".join(out) + r"\Z")
+
+
+def _matcher(pattern: str):
+    pattern = pattern.strip()
+    if pattern.startswith("./"):
+        pattern = pattern[2:]
+    anchored = "/" in pattern
+    regex = glob_regex(pattern.lstrip("/"))
+
+    def match(relative: str) -> bool:
+        if anchored:
+            return bool(regex.match(relative))
+        return bool(regex.match(relative.rsplit("/", 1)[-1]))
+
+    return match
+
+
+def glob_files(args: dict[str, Any], ctx: ToolContext) -> str:
+    root = ctx.resolve(args.get("path"), must_exist=True)
+    match = _matcher(args["pattern"])
+    deadline = time.monotonic() + SEARCH_SECONDS
+    matches: list[str] = []
+    note = ""
+    for file in _iter_files(root):
+        if match(file.relative_to(root).as_posix()):
+            matches.append(ctx.display(file))
+            if len(matches) >= MAX_GLOB:
+                note = f"... (stopped at {MAX_GLOB} matches; use a narrower pattern or path)"
+                break
+        if time.monotonic() > deadline:
+            note = "... (search stopped at its time limit; the list is incomplete)"
+            break
+    if note:
+        matches.append(note)
+    return "\n".join(matches) or "no matches"
+
+
+def grep(args: dict[str, Any], ctx: ToolContext) -> str:
+    root = ctx.resolve(args.get("path"), must_exist=True)
+    pattern = args["pattern"]
+    if args.get("literal"):
+        pattern = re.escape(pattern)
+    try:
+        regex = re.compile(pattern, 0 if args.get("case_sensitive", True) else re.IGNORECASE)
+    except re.error as exc:
+        raise ToolError(
+            f"invalid regex: {exc}. Escape special characters such as ( ) [ ] . or set "
+            "literal=true to search for the text as written"
+        ) from exc
+    mode = args.get("output_mode") or "content"
+    context = min(max(int(args.get("context") or 0), 0), 10)
+    max_count = min(max(int(args.get("max_count") or 300), 1), 2000)
+    include = _matcher(args["glob"]) if args.get("glob") else None
+    files = [root] if root.is_file() else list(_iter_files(root))
+    deadline = time.monotonic() + SEARCH_SECONDS
+    results: list[str] = []
+    found = 0
+    note = ""
+    for file in files:
+        if include and file != root and not include(file.relative_to(root).as_posix()):
+            continue
+        if time.monotonic() > deadline:
+            note = "... (search stopped at its time limit; narrow the path or glob)"
+            break
+        try:
+            if file.stat().st_size > MAX_FILE_BYTES:
+                continue
+            with file.open(encoding="utf-8", errors="strict") as handle:
+                lines = handle.read().splitlines()
+        except (UnicodeDecodeError, OSError):
+            continue
+        hits = [n for n, line in enumerate(lines, start=1) if regex.search(line)]
+        if not hits:
+            continue
+        name = ctx.display(file)
+        if mode == "files_with_matches":
+            results.append(name)
+            found += 1
+        elif mode == "count":
+            results.append(f"{name}: {len(hits)}")
+            found += 1
+        else:
+            shown: set[int] = set()
+            for number in hits:
+                if found >= max_count:
+                    break
+                found += 1
+                low, high = max(1, number - context), min(len(lines), number + context)
+                if context and shown and low > max(shown) + 1:
+                    results.append("--")
+                for n in range(low, high + 1):
+                    if n in shown:
+                        continue
+                    shown.add(n)
+                    sep = ":" if n == number or n in hits else "-"
+                    results.append(f"{name}:{n}{sep} {lines[n - 1].rstrip()[:300]}")
+        if found >= max_count:
+            note = f"... (stopped at {max_count} matches; narrow the pattern or path, or raise max_count)"
+            break
+    if note:
+        results.append(note)
+    return "\n".join(results) or "no matches"
+
+
+_DANGEROUS = re.compile(
+    r"(^|[;&|\s])(rm\s+-[a-z]*r|sudo\b|mkfs|dd\s+if=|shutdown|reboot|chmod\s+-R\s+777|curl\b[^|]*\|\s*(sh|bash)|"
+    r"wget\b[^|]*\|\s*(sh|bash)|git\s+push|git\s+reset\s+--hard|:\(\)\s*\{)",
+)
+_READ_ONLY_COMMANDS = {
+    "ls",
+    "cat",
+    "head",
+    "tail",
+    "wc",
+    "grep",
+    "rg",
+    "find",
+    "pwd",
+    "echo",
+    "which",
+    "file",
+    "stat",
+    "du",
+    "kicad-cli",
+    "git",
+    "python",
+    "python3",
+    "diff",
+    "sort",
+    "uniq",
+}
+
+
+def dangerous_command(command: str) -> bool:
+    return bool(_DANGEROUS.search(command))
+
+
+def simple_command(command: str) -> bool:
+    """True for a single command without chaining or redirection whose program is well known."""
+    if re.search(r"(\n|&&|\|\||[;&|`<>]|\$\()", command):
+        return False
+    words = command.strip().split()
+    return bool(words) and Path(words[0]).name in _READ_ONLY_COMMANDS
+
+
+def _shell_env() -> dict[str, str]:
+    return {**os.environ, "QT_QPA_PLATFORM": "offscreen"}
+
+
+async def execute(args: dict[str, Any], ctx: ToolContext) -> str | dict[str, Any]:
+    if ctx.read_only:
+        raise ToolError("shell commands are disabled in read-only sessions")
+    command = args["command"]
+    cwd = ctx.resolve(args.get("cwd"), must_exist=True)
+    if args.get("background"):
+        return await start_background(
+            command, cwd, _shell_env(), ctx, str(args.get("description") or "")
+        )
+    timeout = min(float(args.get("timeout") or ctx.shell_timeout), 1800.0)
+    process = await asyncio.create_subprocess_shell(
+        command,
+        cwd=cwd,
+        stdin=asyncio.subprocess.DEVNULL,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.STDOUT,
+        env=_shell_env(),
+        start_new_session=os.name != "nt",
+    )
+    try:
+        output, _ = await asyncio.wait_for(process.communicate(), timeout=timeout)
+    except (TimeoutError, asyncio.CancelledError) as exc:
+        try:
+            os.killpg(os.getpgid(process.pid), 9)
+        except (ProcessLookupError, PermissionError, OSError, AttributeError):
+            process.kill()
+        await process.wait()
+        if isinstance(exc, asyncio.CancelledError):
+            raise
+        raise ToolError(
+            f"command timed out after {timeout:.0f}s and was stopped. For long jobs use "
+            "background=true and process_output"
+        ) from None
+    text = output.decode("utf-8", errors="replace").replace("\r\n", "\n").rstrip()
+    # Long output is saved to a file by the executor, with a head/tail preview.
+    return f"{text or '(no output)'}\n[exit code {process.returncode}]"
+
+
+async def ask_user(args: dict[str, Any], ctx: ToolContext) -> str:
+    if ctx.ask_user is None:
+        return "No user is available to answer. State your assumption and continue."
+    options = [str(o) for o in args.get("options") or []]
+    answer = await ctx.ask_user(args["question"], options)
+    return answer or "(no answer)"
+
+
+_PATH = {"type": "string", "description": "Path relative to the workspace root"}
+
+FILE_TOOLS = [
+    Tool(
+        "ls",
+        "List a directory in the workspace.",
+        {"type": "object", "properties": {"path": _PATH}},
+        ls,
+    ),
+    Tool(
+        "read_file",
+        "Read a file with line numbers. KiCad files are text (S-expressions): find the part you "
+        "need with grep first, then read that range with offset/limit; one call returns at most "
+        f"{MAX_READ_LINES} lines or about {MAX_READ_CHARS // 1000}k characters and says where to "
+        "continue. Images (png, jpg, gif, webp) are shown to you as images, so you can look at "
+        "board renders and screenshots; set as_image=true to see an SVG (e.g. a KiCad export) "
+        "rendered. PDFs (datasheets) are converted to text, up to "
+        f"{MAX_PDF_PAGES} pages per call (pages='1-5'). Oversized tool results that were saved "
+        "to .traceforge/scratch/tool-output/ can be paged through here too.",
+        {
+            "type": "object",
+            "properties": {
+                "path": _PATH,
+                "offset": {"type": "integer", "description": "1-based first line"},
+                "limit": {"type": "integer", "description": f"max lines (<= {MAX_READ_LINES})"},
+                "pages": {"type": "string", "description": "PDF page range, e.g. '3' or '1-5'"},
+                "as_image": {"type": "boolean", "description": "render an SVG to an image"},
+            },
+            "required": ["path"],
+        },
+        read_file,
+        spill=False,
+    ),
+    Tool(
+        "write_file",
+        "Create or overwrite a text file in the workspace. Returns a diff when it replaces an "
+        "existing file. Prefer edit_file or multi_edit for changes to existing files.",
+        {
+            "type": "object",
+            "properties": {"path": _PATH, "content": {"type": "string"}},
+            "required": ["path", "content"],
+        },
+        write_file,
+        ToolKind.WRITE,
+        "path",
+    ),
+    Tool(
+        "edit_file",
+        "Replace exact text in a file. old_string must match exactly once unless replace_all is "
+        "true. Returns a diff of the change. Prefer the structured kicad_* tools for placements, "
+        "tracks and fields.",
+        {
+            "type": "object",
+            "properties": {
+                "path": _PATH,
+                "old_string": {"type": "string"},
+                "new_string": {"type": "string"},
+                "replace_all": {"type": "boolean"},
+            },
+            "required": ["path", "old_string", "new_string"],
+        },
+        edit_file,
+        ToolKind.WRITE,
+        "path",
+    ),
+    Tool(
+        "multi_edit",
+        "Apply several exact-text replacements to one file in order, all or nothing: if any "
+        "edit does not match, the file is left unchanged. Each edit sees the result of the "
+        "previous one. Use it instead of many edit_file calls on the same file.",
+        {
+            "type": "object",
+            "properties": {
+                "path": _PATH,
+                "edits": {
+                    "type": "array",
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "old_string": {"type": "string"},
+                            "new_string": {"type": "string"},
+                            "replace_all": {"type": "boolean"},
+                        },
+                        "required": ["old_string", "new_string"],
+                    },
+                },
+            },
+            "required": ["path", "edits"],
+        },
+        multi_edit,
+        ToolKind.WRITE,
+        "path",
+    ),
+    Tool(
+        "delete_file",
+        "Delete a file (or a directory with recursive=true) in the workspace. This cannot be "
+        "undone, so it asks the user unless approvals are set to yolo.",
+        {
+            "type": "object",
+            "properties": {"path": _PATH, "recursive": {"type": "boolean"}},
+            "required": ["path"],
+        },
+        delete_file,
+        ToolKind.WRITE,
+        "path",
+    ),
+    Tool(
+        "write_binary_file",
+        "Write a binary file (base64 data), e.g. an image or an archive you generated.",
+        {
+            "type": "object",
+            "properties": {
+                "path": _PATH,
+                "data": {"type": "string", "description": "base64-encoded content"},
+            },
+            "required": ["path", "data"],
+        },
+        write_binary_file,
+        ToolKind.WRITE,
+        "path",
+    ),
+    Tool(
+        "glob",
+        "Find files by glob pattern. '*' stays within a folder, '**' crosses folders, {a,b} "
+        "gives alternatives: '*.kicad_sch' (any depth), 'hardware/**/*.kicad_{sch,pcb}'. A "
+        f"pattern without '/' matches file names at any depth. At most {MAX_GLOB} results.",
+        {
+            "type": "object",
+            "properties": {"pattern": {"type": "string"}, "path": _PATH},
+            "required": ["pattern"],
+        },
+        glob_files,
+    ),
+    Tool(
+        "grep",
+        "Search file contents with a regular expression (set literal=true to search for text "
+        "as written, e.g. '(property \"Reference\"'). output_mode: 'content' (default, "
+        "file:line: text, with optional context lines), 'files_with_matches' or 'count'. "
+        "Stops at max_count matches (default 300) and says so.",
+        {
+            "type": "object",
+            "properties": {
+                "pattern": {"type": "string"},
+                "path": _PATH,
+                "glob": {
+                    "type": "string",
+                    "description": "only files matching this glob, e.g. *.kicad_pcb",
+                },
+                "case_sensitive": {"type": "boolean"},
+                "literal": {"type": "boolean", "description": "match the pattern as plain text"},
+                "output_mode": {
+                    "type": "string",
+                    "enum": ["content", "files_with_matches", "count"],
+                },
+                "context": {"type": "integer", "description": "lines before/after (<= 10)"},
+                "max_count": {"type": "integer", "description": "stop after this many matches"},
+            },
+            "required": ["pattern"],
+        },
+        grep,
+    ),
+    Tool(
+        "execute",
+        "Run a shell command in the workspace and return its output and exit code (default "
+        "timeout 120 s, max 1800; a command that times out is stopped). Use it for kicad-cli, "
+        "scripts and simulations. For long jobs set background=true: the command keeps running, "
+        "you get an id at once, and process_output reports its progress. Very long output is "
+        "saved to a file and you get the head and tail.",
+        {
+            "type": "object",
+            "properties": {
+                "command": {"type": "string"},
+                "cwd": _PATH,
+                "timeout": {"type": "number", "description": "seconds, max 1800"},
+                "background": {"type": "boolean", "description": "run detached; returns an id"},
+                "description": {"type": "string", "description": "what the command is for"},
+            },
+            "required": ["command"],
+        },
+        execute,
+        ToolKind.SHELL,
+        "command",
+    ),
+    Tool(
+        "ask_user",
+        "Ask the user a question when a decision is genuinely theirs (requirements, trade-offs, budget). "
+        "Offer options when there are clear choices.",
+        {
+            "type": "object",
+            "properties": {
+                "question": {"type": "string"},
+                "options": {"type": "array", "items": {"type": "string"}},
+            },
+            "required": ["question"],
+        },
+        ask_user,
+        ToolKind.INTERACTIVE,
+    ),
+]