seedcode-cli 6.1.5__py3-none-any.whl

seedcode/tools/desktop.py

@@ -0,0 +1,371 @@
+"""Desktop tools: the Computer Engine's AI-facing contract.
+
+This module is the *entire* surface the AI has on the local machine, and it is
+deliberately narrow. The AI reasons and decides; the deterministic
+:class:`~seedcode.computer.engine.ComputerEngine` does the work. So the AI never
+moves the mouse, presses keys, waits for windows, retries, or handles OCR —
+those live below this line.
+
+What the AI can call:
+
+* ``computer_run`` — run a high-level skill from the catalog (the main verb).
+* ``ui_click`` / ``ui_double_click`` / ``ui_right_click`` / ``ui_type`` /
+  ``ui_wait_for`` / ``ui_assert`` — semantic UI actions whose targets are
+  *descriptions* ("the Submit button"); the engine resolves coordinates.
+* ``computer_state`` — read engine memory (focused app, pointer, recent work).
+* ``computer_see`` — a semantic snapshot to replan against unknown UI.
+* ``desktop_screenshot`` / ``desktop_windows`` / ``desktop_screen_info`` —
+  observation for vision providers and replanning.
+
+No coordinate-, keystroke-, or selector-bearing argument is exposed. Capability
+is gated by the unified :class:`~seedcode.tools.permissions.PermissionLevel`
+(desktop needs ``DESKTOP``; sensitive skills need ``FULL_SYSTEM``), and every
+sensitive action is confirmed per-action through the session's Desktop Control
+gate.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .base import ToolError, ToolResult, register
+from .permissions import PermissionLevel
+
+if TYPE_CHECKING:
+    from ..computer.engine import ComputerEngine
+    from .permissions import PermissionManager
+
+
+# Shared lazy controller: one instance per session, reused by the engine and
+# by the hand commands (/screenshot, /windows, /computer) that don't need a
+# permission gate. Built on first use so importing this module never pulls in
+# the desktop libraries.
+_controller: "Any | None" = None
+
+
+def get_controller() -> "Any":
+    """Return the shared :class:`ComputerController`, building it on first use."""
+    global _controller
+    if _controller is None:
+        from ..computer.controller import ComputerController
+
+        _controller = ComputerController()
+    return _controller
+
+
+def reset_controller() -> None:
+    """Drop the cached controller and engine (tests inject fakes via this)."""
+    global _controller
+    _controller = None
+    from ..computer import reset_engine
+
+    reset_engine()
+    # Operator-layer engines hold driver references too; drop them so a
+    # rebuilt session never reuses stale desktop state.
+    from ..computer import screen_state, browser_extract
+
+    screen_state.reset_screen_engine()
+    browser_extract.reset_web_extractor()
+
+
+def _engine(perm: "PermissionManager") -> "ComputerEngine":
+    """Return the session Computer Engine, or raise a model-readable error."""
+    from ..computer import get_engine, is_available
+
+    if not perm.level.allows_desktop:
+        raise ToolError(
+            "Desktop control needs Desktop permission or higher. The user can "
+            "enable it with /assist on or raise it with /permission desktop."
+        )
+    if perm.desktop is None or not perm.desktop.enabled:
+        raise ToolError(
+            "Desktop tools are disabled. The user can enable them with /assist on."
+        )
+    ok, reason = is_available()
+    if not ok:
+        raise ToolError(f"Desktop control is unavailable: {reason}")
+    return get_engine(perm, controller=get_controller())
+
+
+def _confirm_sensitive(perm: "PermissionManager", skill_name: str, params: dict) -> None:
+    """Per-action confirmation for sensitive skills, via the Desktop gate.
+
+    Sensitive skills additionally require Full System and are never remembered
+    ("Always" is downgraded to "Once" by the gate), so each one is approved
+    individually.
+    """
+    from ..computer.permissions import CATEGORY_SYSTEM
+
+    perm.require(PermissionLevel.FULL_SYSTEM, f"sensitive skill '{skill_name}'")
+    desc = f"{skill_name} {params}".strip()
+    perm.desktop.check(CATEGORY_SYSTEM, desc)  # type: ignore[union-attr]
+
+
+def _gate_control(perm: "PermissionManager", description: str) -> None:
+    """Non-sensitive desktop confirmation (remembered per session)."""
+    from ..computer.permissions import CATEGORY_CONTROL
+
+    perm.desktop.check(CATEGORY_CONTROL, description)  # type: ignore[union-attr]
+
+
+def _dispatch(perm: "PermissionManager", name: str, params: dict[str, Any],
+              expected: dict[str, Any] | None = None) -> ToolResult:
+    """Shared path for skills and semantic actions: gate, run, report."""
+    from ..computer.skills import REGISTRY
+
+    engine = _engine(perm)
+    skill = REGISTRY.get(name)
+    if skill is not None and skill.sensitive:
+        _confirm_sensitive(perm, skill.name, params)
+    else:
+        _gate_control(perm, f"{name} {params}".strip())
+
+    result = engine.run_skill(name, params, expected)
+    _queue_screenshot(perm)
+    return ToolResult(result.ok, result.for_model())
+
+
+# --- primary verb: run a skill ----------------------------------------------
+@register(
+    "computer_run",
+    "Run a high-level Computer Engine skill by name (e.g. launch_app, "
+    "google_search, create_python_project). The engine expands it into "
+    "verified, deterministic steps and recovers from failures on its own — you "
+    "choose the skill and its parameters, nothing lower-level. See the skill "
+    "catalog in the system prompt for available skills.",
+    {
+        "skill": "skill name from the catalog",
+        "params": "(optional) object of the skill's parameters",
+        "expected": "(optional) outcome to verify, e.g. {\"window\": \"Notepad\"}",
+    },
+    mutates=True,
+    group="desktop",
+    types={"params": "object", "expected": "object"},
+)
+def _computer_run(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    name = str(args.get("skill", "")).strip()
+    if not name:
+        return ToolResult(False, "skill is required.")
+    params = args.get("params") or {}
+    if not isinstance(params, dict):
+        return ToolResult(False, "params must be an object.")
+    expected = args.get("expected")
+    if expected is not None and not isinstance(expected, dict):
+        return ToolResult(False, "expected must be an object.")
+    return _dispatch(perm, name, params, expected)
+
+
+# --- semantic UI actions (descriptions, never coordinates) -------------------
+def _semantic(perm: "PermissionManager", verb: str, args: dict[str, Any]) -> ToolResult:
+    target = str(args.get("target", "")).strip()
+    if not target:
+        return ToolResult(False, "target description is required.")
+    params: dict[str, Any] = {"target": target}
+    if "text" in args:
+        params["text"] = args.get("text", "")
+    if "secret" in args:
+        params["secret"] = str(args.get("secret", "")).lower() in ("true", "1", "yes")
+    return _dispatch(perm, verb, params)
+
+
+@register(
+    "ui_click",
+    "Click a UI element described in plain words (e.g. \"the Save button\"). "
+    "The engine locates it — never pass coordinates.",
+    {"target": "description of the element to click"},
+    mutates=True,
+    group="desktop",
+)
+def _ui_click(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    return _semantic(perm, "ui_click", args)
+
+
+@register(
+    "ui_double_click",
+    "Double-click a described UI element (e.g. \"the project folder\").",
+    {"target": "description of the element to double-click"},
+    mutates=True,
+    group="desktop",
+)
+def _ui_double_click(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    return _semantic(perm, "ui_double_click", args)
+
+
+@register(
+    "ui_right_click",
+    "Right-click a described UI element to open its context menu.",
+    {"target": "description of the element to right-click"},
+    mutates=True,
+    group="desktop",
+)
+def _ui_right_click(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    return _semantic(perm, "ui_right_click", args)
+
+
+@register(
+    "ui_type",
+    "Type text into a described field (e.g. \"the search box\"). Set secret=true "
+    "for passwords. The engine focuses the field and types — no coordinates.",
+    {
+        "target": "description of the field to type into",
+        "text": "the text to type",
+        "secret": "(optional) true when the text is a password or secret",
+    },
+    mutates=True,
+    group="desktop",
+)
+def _ui_type(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    if "text" not in args:
+        return ToolResult(False, "text is required.")
+    return _semantic(perm, "ui_type", args)
+
+
+@register(
+    "ui_wait_for",
+    "Wait until a described element or window appears before continuing.",
+    {"target": "description of what to wait for"},
+    mutates=False,
+    group="desktop",
+)
+def _ui_wait_for(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    return _semantic(perm, "ui_wait_for", args)
+
+
+@register(
+    "ui_assert",
+    "Check that a described element or text is present, without acting on it.",
+    {"target": "description of what should be present"},
+    mutates=False,
+    group="desktop",
+)
+def _ui_assert(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    return _semantic(perm, "ui_assert", args)
+
+
+# --- observation -------------------------------------------------------------
+@register(
+    "computer_state",
+    "Read the Computer Engine's memory: focused app/window, pointer, clipboard, "
+    "terminal directory, current project, and recent actions. Prefer this over "
+    "re-inspecting the screen — the engine tracks state for you.",
+    {},
+    mutates=False,
+    group="desktop",
+)
+def _computer_state(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    engine = _engine(perm)
+    return ToolResult(True, engine.state().describe())
+
+
+@register(
+    "computer_see",
+    "Get a semantic snapshot of the active (or named) window: the elements and "
+    "visible text, described in words. Use this to replan when the UI is "
+    "unfamiliar. Returns descriptions, never coordinates.",
+    {"window": "(optional) part of a window title; default: the active window"},
+    mutates=False,
+    group="desktop",
+)
+def _computer_see(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    engine = _engine(perm)
+    window = str(args.get("window", "") or "").strip() or None
+    _gate_control(perm, f"inspect UI of {window or 'the active window'}")
+    out = engine.see(window)
+    _queue_screenshot(perm)
+    return ToolResult(True, out)
+
+
+@register(
+    "desktop_screenshot",
+    "Capture a screenshot (whole desktop, a monitor, or a region) to a PNG "
+    "file; optionally OCR its text.",
+    {
+        "monitor": "(optional) 1-based monitor number",
+        "region": "(optional) [left, top, width, height]",
+        "ocr": "(optional) true to also extract text via OCR",
+    },
+    mutates=False,
+    group="desktop",
+)
+def _desktop_screenshot(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    engine = _engine(perm)
+    _gate_control(perm, "take a screenshot")
+    controller = engine.controller
+
+    region = None
+    raw_region = args.get("region")
+    if raw_region is not None:
+        try:
+            left, top, width, height = (int(v) for v in raw_region)
+            region = (left, top, width, height)
+        except (TypeError, ValueError):
+            return ToolResult(False, "region must be [left, top, width, height] integers.")
+    monitor = None
+    if args.get("monitor") is not None:
+        try:
+            monitor = int(args["monitor"])
+        except (TypeError, ValueError):
+            return ToolResult(False, "monitor must be an integer (1-based).")
+
+    try:
+        path = controller.screenshot(region=region, monitor=monitor)
+    except Exception as exc:
+        return ToolResult(False, f"Screenshot failed: {exc}")
+    output = f"Screenshot saved: {path}"
+    if str(args.get("ocr", "")).lower() in ("true", "1", "yes"):
+        output += "\n[OCR]\n" + controller.vision.ocr_screenshot(path)
+    _queue_screenshot(perm, str(path))
+    return ToolResult(True, output)
+
+
+@register(
+    "desktop_windows",
+    "List all open windows with their titles, positions, and sizes.",
+    {},
+    mutates=False,
+    group="desktop",
+)
+def _desktop_windows(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    engine = _engine(perm)
+    _gate_control(perm, "list open windows")
+    try:
+        return ToolResult(True, engine.controller.list_windows())
+    except Exception as exc:
+        return ToolResult(False, f"Could not list windows: {exc}")
+
+
+@register(
+    "desktop_screen_info",
+    "Report screen resolution and multi-monitor layout.",
+    {},
+    mutates=False,
+    group="desktop",
+)
+def _desktop_screen_info(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    engine = _engine(perm)
+    _gate_control(perm, "read screen info")
+    try:
+        return ToolResult(True, engine.controller.screen_info())
+    except Exception as exc:
+        return ToolResult(False, f"Could not read screen info: {exc}")
+
+
+# --- screenshot hand-off to the agent loop -----------------------------------
+def _queue_screenshot(perm: "PermissionManager", path: str | None = None) -> None:
+    """Queue a screenshot for image-capable providers (best-effort).
+
+    The agent loop attaches the encoded image to the next tool-results message
+    when the active provider supports vision. Failure here never fails a tool.
+    """
+    desktop = perm.desktop
+    if desktop is None:
+        return
+    try:
+        from ..computer import screen
+
+        if path is None:
+            path = str(screen.capture())
+        desktop.pending_images.append(screen.encode_png_base64(path))
+        del desktop.pending_images[:-1]  # keep only the latest frame
+    except Exception:
+        pass

seedcode/tools/filesystem.py

@@ -0,0 +1,309 @@
+"""Filesystem tools: read, write, list, delete — plus the project indexer.
+
+Multi-file editing is simply several ``write_file``/``edit_file`` calls in one
+agent turn; each one passes the same permission gate. The indexer produces a
+compact tree of the workspace so the model can orient itself without reading
+every file.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from .base import ToolResult, int_arg, register
+from .permissions import CATEGORY_DELETE
+from .textio import TextFile, read_text_file, write_text_file
+
+if TYPE_CHECKING:
+    from .permissions import PermissionManager
+
+# Read caps: a tool call must never dump a huge binary/log into the context.
+_MAX_READ_BYTES = 256 * 1024
+_MAX_INDEX_ENTRIES = 400
+
+# Directories that never belong in a project index.
+_INDEX_SKIP = {
+    ".git", "__pycache__", ".pytest_cache", "node_modules", ".venv", "venv",
+    "dist", "build", ".mypy_cache", ".ruff_cache", ".idea", ".vscode",
+}
+
+
+@register(
+    "read_file",
+    "Read a text file (optionally a line range).",
+    {
+        "path": "file path",
+        "start_line": "(optional) first line, 1-based",
+        "end_line": "(optional) last line, inclusive",
+    },
+    mutates=False,
+    types={"start_line": "integer", "end_line": "integer"},
+)
+def _read_file(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args["path"])
+    perm.check_read(path)
+    if not path.is_file():
+        return ToolResult(False, f"File not found: {path}")
+    if path.stat().st_size > _MAX_READ_BYTES and "start_line" not in args:
+        return ToolResult(
+            False,
+            f"File is large ({path.stat().st_size} bytes). "
+            "Read it in ranges with start_line/end_line.",
+        )
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError as exc:
+        return ToolResult(False, f"Could not read {path}: {exc}")
+
+    lines = text.splitlines()
+    start = int_arg(args, "start_line", 1, 1, 10_000_000)
+    end = min(len(lines), int_arg(args, "end_line", len(lines), 0, 10_000_000))
+    numbered = [f"{i}\t{lines[i - 1]}" for i in range(start, end + 1)]
+    header = f"{path} ({len(lines)} lines, showing {start}-{end})"
+    return ToolResult(True, header + "\n" + "\n".join(numbered))
+
+
+@register(
+    "write_file",
+    "Create or overwrite a file with the given content.",
+    {"path": "file path", "content": "full new file content"},
+    mutates=True,
+)
+def _write_file(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args["path"])
+    perm.check_write(path)
+    content = str(args["content"])
+
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(content, encoding="utf-8")
+    except OSError as exc:
+        return ToolResult(False, f"Could not write {path}: {exc}")
+
+    # VERIFICATION: Read back to confirm write succeeded
+    try:
+        written = path.read_text(encoding="utf-8", errors="replace")
+        if written != content:
+            return ToolResult(
+                False,
+                f"Verification failed: {path} was written but content doesn't match. "
+                f"Expected {len(content)} chars, read back {len(written)} chars."
+            )
+    except OSError as exc:
+        return ToolResult(
+            False,
+            f"Write completed but verification failed: could not read {path}: {exc}"
+        )
+
+    return ToolResult(True, f"Wrote {len(content)} chars to {path} (verified)")
+
+
+@register(
+    "delete_file",
+    "Delete a single file (never a directory).",
+    {"path": "file path"},
+    mutates=True,
+)
+def _delete_file(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args["path"])
+    perm.check_write(path)
+    if path.is_dir():
+        return ToolResult(False, f"Refusing to delete a directory: {path}")
+    if not path.exists():
+        return ToolResult(False, f"File not found: {path}")
+    perm.confirm_action(CATEGORY_DELETE, str(path))
+    try:
+        path.unlink()
+    except OSError as exc:
+        return ToolResult(False, f"Could not delete {path}: {exc}")
+
+    # VERIFICATION: Confirm file no longer exists
+    if path.exists():
+        return ToolResult(
+            False,
+            f"Delete command completed but {path} still exists. Possible permission or filesystem issue."
+        )
+
+    return ToolResult(True, f"Deleted {path} (verified)")
+
+
+@register(
+    "list_dir",
+    "List the entries of a directory.",
+    {"path": "(optional) directory path, defaults to the workspace root"},
+    mutates=False,
+)
+def _list_dir(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args.get("path") or ".")
+    perm.check_read(path)
+    if not path.is_dir():
+        return ToolResult(False, f"Not a directory: {path}")
+    try:
+        entries = sorted(path.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+    except OSError as exc:
+        return ToolResult(False, f"Could not list {path}: {exc}")
+    lines = [f"{'d' if e.is_dir() else 'f'}  {e.name}" for e in entries]
+    return ToolResult(True, f"{path}\n" + ("\n".join(lines) or "(empty)"))
+
+
+@register(
+    "append_file",
+    "Append content to the end of a file (created if missing).",
+    {"path": "file path", "content": "text to append"},
+    mutates=True,
+)
+def _append_file(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args["path"])
+    perm.check_write(path)
+    content = str(args["content"])
+    if not content:
+        return ToolResult(False, "content is empty; nothing to append.")
+
+    try:
+        if path.is_file():
+            tf = read_text_file(path)  # preserve encoding + line endings
+            tf.text += content.replace("\r\n", "\n")
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            tf = TextFile(text=content.replace("\r\n", "\n"), encoding="utf-8", newline="\n")
+        write_text_file(path, tf)
+    except OSError as exc:
+        return ToolResult(False, f"Could not append to {path}: {exc}")
+
+    # VERIFICATION: the appended text must be at the end of the file
+    try:
+        if not read_text_file(path).text.endswith(content.replace("\r\n", "\n")):
+            return ToolResult(
+                False,
+                f"Append completed but verification failed: {path} does not end "
+                "with the appended text.",
+            )
+    except OSError as exc:
+        return ToolResult(
+            False, f"Append completed but verification failed: could not read {path}: {exc}"
+        )
+
+    return ToolResult(True, f"Appended {len(content)} chars to {path} (verified)")
+
+
+@register(
+    "create_directory",
+    "Create a directory (parents included).",
+    {"path": "directory path"},
+    mutates=True,
+)
+def _create_directory(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args["path"])
+    perm.check_write(path)
+    if path.is_file():
+        return ToolResult(False, f"A file already exists at {path}.")
+    existed = path.is_dir()
+    try:
+        path.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        return ToolResult(False, f"Could not create directory {path}: {exc}")
+    if not path.is_dir():
+        return ToolResult(False, f"mkdir completed but {path} does not exist.")
+    return ToolResult(True, f"Directory {'already existed' if existed else 'created'}: {path}")
+
+
+@register(
+    "rename_file",
+    "Rename a file within its directory (use move_file to change directories).",
+    {"path": "current file path", "new_name": "new file name (no directories)"},
+    mutates=True,
+)
+def _rename_file(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args["path"])
+    new_name = str(args["new_name"]).strip()
+    if not new_name or any(sep in new_name for sep in ("/", "\\")):
+        return ToolResult(
+            False, "new_name must be a bare file name — use move_file to change directories."
+        )
+    target = path.with_name(new_name)
+    perm.check_write(path)
+    perm.check_write(target)
+    if not path.exists():
+        return ToolResult(False, f"File not found: {path}")
+    if target.exists():
+        return ToolResult(False, f"Refusing to overwrite existing {target}.")
+    try:
+        path.rename(target)
+    except OSError as exc:
+        return ToolResult(False, f"Could not rename {path}: {exc}")
+    if not target.exists() or path.exists():
+        return ToolResult(False, f"Rename completed but verification failed for {target}.")
+    return ToolResult(True, f"Renamed {path} -> {target} (verified)")
+
+
+@register(
+    "move_file",
+    "Move a file to another path (directories created as needed).",
+    {"path": "current file path", "destination": "new file path"},
+    mutates=True,
+)
+def _move_file(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    path = perm.resolve(args["path"])
+    target = perm.resolve(args["destination"])
+    perm.check_write(path)
+    perm.check_write(target)  # outside-workspace destinations hit the gate
+    if not path.exists():
+        return ToolResult(False, f"File not found: {path}")
+    if path.is_dir():
+        return ToolResult(False, f"Refusing to move a directory: {path}")
+    if target.is_dir():
+        target = target / path.name
+    if target.exists():
+        return ToolResult(False, f"Refusing to overwrite existing {target}.")
+    try:
+        target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.move(str(path), str(target))  # handles cross-drive on Windows
+    except OSError as exc:
+        return ToolResult(False, f"Could not move {path}: {exc}")
+    if not target.exists() or path.exists():
+        return ToolResult(False, f"Move completed but verification failed for {target}.")
+    return ToolResult(True, f"Moved {path} -> {target} (verified)")
+
+
+def _walk_index(root: Path, prefix: str, lines: list[str]) -> None:
+    """Depth-first tree walk, capped at _MAX_INDEX_ENTRIES lines."""
+    if len(lines) >= _MAX_INDEX_ENTRIES:
+        return
+    try:
+        entries = sorted(root.iterdir(), key=lambda p: (p.is_file(), p.name.lower()))
+    except OSError:
+        return
+    for entry in entries:
+        if len(lines) >= _MAX_INDEX_ENTRIES:
+            lines.append(f"{prefix}... (index capped at {_MAX_INDEX_ENTRIES} entries)")
+            return
+        if entry.name in _INDEX_SKIP or entry.name.startswith("."):
+            continue
+        if entry.is_dir():
+            lines.append(f"{prefix}{entry.name}/")
+            _walk_index(entry, prefix + "  ", lines)
+        else:
+            try:
+                size = entry.stat().st_size
+            except OSError:
+                size = 0
+            lines.append(f"{prefix}{entry.name}  ({size} B)")
+
+
+def build_index(perm: "PermissionManager") -> str:
+    """Compact workspace tree (shared by the tool and the /index command)."""
+    lines: list[str] = [f"{perm.workspace}/"]
+    _walk_index(perm.workspace, "  ", lines)
+    return "\n".join(lines)
+
+
+@register(
+    "project_index",
+    "Get a compact tree of the whole workspace (files, sizes).",
+    {},
+    mutates=False,
+)
+def _project_index(perm: "PermissionManager", args: dict[str, Any]) -> ToolResult:
+    return ToolResult(True, build_index(perm))