kiwimatecoder 0.1.0__py3-none-any.whl

kiwimatecoder/tools/read_file.py

@@ -0,0 +1,113 @@
+"""read_file tool: read a text file from the workspace."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from kiwimatecoder.documents import extract_document
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+from kiwimatecoder.tools.paths import PathError, resolve_for_read
+
+MAX_BYTES = 256 * 1024
+
+
+def _is_binary(sample: bytes) -> bool:
+    return b"\x00" in sample
+
+
+def _read_file(args: dict[str, Any], session: Session) -> ToolResult:
+    path = str(args.get("path") or "")
+    if not path:
+        return ToolResult.error("'path' is required")
+    try:
+        resolved = resolve_for_read(
+            path,
+            session.workspace_root,
+            trusted=bool(getattr(session, "trusted_workspace", False)),
+        )
+    except PathError as exc:
+        return ToolResult.error(str(exc))
+
+    if not resolved.exists():
+        return ToolResult.error(f"File not found: {path}")
+    if resolved.is_dir():
+        return ToolResult.error(f"'{path}' is a directory, use list_dir")
+
+    document = extract_document(resolved)
+    if document is not None:
+        content, kind = document
+        return ToolResult(
+            content=(
+                f"[{kind} document: extracted text; offset/limit are ignored "
+                f"for documents]\n{content or '[empty document]'}"
+            )
+        )
+
+    data = resolved.read_bytes()
+    if _is_binary(data[:1024]):
+        return ToolResult.error(f"'{path}' appears to be a binary file")
+
+    text = data.decode("utf-8", "replace")
+    lines = text.splitlines()
+
+    try:
+        offset = int(args.get("offset", 0) or 0)
+    except (TypeError, ValueError):
+        return ToolResult.error("'offset' must be an integer")
+    if offset < 0:
+        return ToolResult.error("'offset' must be non-negative")
+    limit = args.get("limit")
+    if limit is not None:
+        try:
+            limit = int(limit)
+        except (TypeError, ValueError):
+            return ToolResult.error("'limit' must be an integer")
+        if limit < 0:
+            return ToolResult.error("'limit' must be non-negative")
+    if offset or limit is not None:
+        end = offset + limit if limit is not None else len(lines)
+        lines = lines[offset:end]
+
+    truncated = False
+    body = "\n".join(lines)
+    if len(body.encode("utf-8")) > MAX_BYTES:
+        body = body.encode("utf-8")[:MAX_BYTES].decode("utf-8", "ignore")
+        truncated = True
+
+    numbered = "\n".join(
+        f"{offset + i + 1}\t{line}" for i, line in enumerate(body.splitlines())
+    )
+    if truncated:
+        numbered += "\n... [truncated: file exceeds 256KB]"
+    return ToolResult(content=numbered or "[empty file]")
+
+
+read_file_tool = FunctionTool(
+    name="read_file",
+    description=(
+        "Read the contents of a text file in the workspace. Returns the file "
+        "with 1-based line numbers. Use offset/limit for large files. Jupyter "
+        "notebooks (.ipynb), PDFs (.pdf), and Word documents (.docx) are "
+        "extracted to text automatically (offset/limit do not apply)."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "path": {
+                "type": "string",
+                "description": "Path to the file, relative to the workspace root.",
+            },
+            "offset": {
+                "type": "integer",
+                "description": "0-based line number to start reading from.",
+            },
+            "limit": {
+                "type": "integer",
+                "description": "Maximum number of lines to read.",
+            },
+        },
+        "required": ["path"],
+    },
+    func=_read_file,
+)

kiwimatecoder/tools/registry.py

@@ -0,0 +1,91 @@
+"""Extensible registry owning the name -> tool map and each tool's source.
+
+The registry implements the mapping protocol so existing callers that treat
+``TOOLS`` as a plain dict keep working (``TOOLS["read_file"]``,
+``TOOLS.get("nope")``, iteration, ``.values()``). Tools registered at import
+time are labelled ``"builtin"``; dynamically registered tools default to a
+``"plugin"`` source and can be loaded from an external source in future.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from typing import Any
+
+from kiwimatecoder.tools.base import FunctionTool
+
+BUILTIN_SOURCE = "builtin"
+PLUGIN_SOURCE = "plugin"
+
+
+class ToolRegistry(Mapping[str, FunctionTool]):
+    """Ordered name -> :class:`FunctionTool` map with source tracking."""
+
+    def __init__(self) -> None:
+        self._tools: dict[str, FunctionTool] = {}
+        self._sources: dict[str, str] = {}
+
+    def register(
+        self,
+        tool: FunctionTool,
+        source: str = BUILTIN_SOURCE,
+        replace: bool = False,
+    ) -> FunctionTool:
+        """Register ``tool``, raising ``ValueError`` on a duplicate name.
+
+        Pass ``replace=True`` to swap an existing tool with the same name.
+        """
+        name = getattr(tool, "name", "")
+        if not name:
+            raise ValueError("Tool name must be non-empty.")
+        if name in self._tools and not replace:
+            raise ValueError(f"Tool '{name}' is already registered.")
+        self._tools[name] = tool
+        self._sources[name] = str(source or BUILTIN_SOURCE)
+        return tool
+
+    def unregister(self, name: str, force: bool = False) -> bool:
+        """Remove a tool, returning whether it was removed.
+
+        Unknown names return ``False``. Built-in tools are protected unless
+        ``force=True`` so a plugin cannot silently shadow core behaviour.
+        """
+        if name not in self._tools:
+            return False
+        if self._sources.get(name) == BUILTIN_SOURCE and not force:
+            return False
+        del self._tools[name]
+        self._sources.pop(name, None)
+        return True
+
+    def __getitem__(self, name: str) -> FunctionTool:
+        return self._tools[name]
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._tools
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._tools)
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def all(self) -> list[FunctionTool]:
+        """Every registered tool in registration order."""
+        return list(self._tools.values())
+
+    def read_only(self) -> list[FunctionTool]:
+        """Every read-only tool (no approval required) in registration order."""
+        return [tool for tool in self._tools.values() if not tool.needs_approval]
+
+    def schemas(self, read_only: bool = False) -> list[dict[str, Any]]:
+        """OpenAI tool schemas, optionally restricted to read-only tools."""
+        tools = self.read_only() if read_only else self.all()
+        return [tool.schema() for tool in tools]
+
+    def sources(self) -> dict[str, list[str]]:
+        """Map each source label to its sorted tool names."""
+        grouped: dict[str, list[str]] = {}
+        for name, source in self._sources.items():
+            grouped.setdefault(source, []).append(name)
+        return {source: sorted(names) for source, names in grouped.items()}

kiwimatecoder/tools/run_bash.py

@@ -0,0 +1,189 @@
+"""run_bash tool: execute a shell command in the workspace.
+
+Note: unlike the read/write/list/search/edit file tools (which use
+resolve_in_workspace for sandboxing), run_bash is not restricted beyond setting
+cwd to the workspace root. The command string is executed via shell=True (with
+user approval in ask/plan modes). Intended for git, pytest, builds, etc.
+
+When remote execution is configured (``config remote enable on``), the command
+runs through SSH or in a devcontainer/Docker container instead, with the remote
+wrapper shown in the approval preview. A missing CLI falls back to the plain
+shell with a warning.
+
+When OS-level sandboxing is enabled (``config sandbox enable on``), the command
+is executed through the platform sandbox instead (macOS seatbelt or Linux
+bubblewrap) and the approval preview shows the wrapped command. A missing
+backend falls back to the plain shell with a warning. Remote execution applies
+first: a remote command is never additionally wrapped in a local sandbox.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+import signal
+import subprocess
+from typing import Any
+
+from kiwimatecoder.config import get_sandbox, load_config
+from kiwimatecoder.remote import remote_preview, wrap_remote_command
+from kiwimatecoder.sandbox import wrap_command
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+
+DEFAULT_TIMEOUT = 120
+MAX_TIMEOUT = 3600
+MAX_OUTPUT = 30_000
+
+_FALLBACK_ARGV = ["/bin/sh", "-c"]
+
+
+def preview(args: dict[str, Any], session: Session) -> str:
+    """Return the command text (and wrappers) for the approval prompt."""
+    command = str(args.get("command", ""))
+    cfg = load_config()
+    remote_argv, remote_warning = wrap_remote_command(
+        command, workspace=session.workspace_root, cfg=cfg
+    )
+    if remote_argv is not None:
+        return remote_preview(command, workspace=session.workspace_root, cfg=cfg)
+
+    text = command
+    if remote_warning:
+        text = f"{command}\n[remote] {remote_warning}"
+
+    settings = get_sandbox(cfg)
+    if not settings["enabled"]:
+        return text
+    argv, warning = wrap_command(command, workspace=session.workspace_root, cfg=cfg)
+    if warning:
+        return f"{text}\n[sandbox] {warning}"
+    mode = "network on" if settings["network"] else "network off"
+    return f"{text}\n[sandbox] wrapped ({mode}): {shlex.join(argv)}"
+
+
+def _truncate(text: str) -> str:
+    if len(text) > MAX_OUTPUT:
+        return text[:MAX_OUTPUT] + "\n... [output truncated]"
+    return text
+
+
+def _popen(
+    command: str, *, argv: list[str] | None, workspace: str
+) -> subprocess.Popen[str]:
+    """Start the command, through ``argv`` when wrapped, else via the shell."""
+    if argv is not None:
+        return subprocess.Popen(
+            argv,
+            shell=False,
+            cwd=workspace,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            start_new_session=True,
+        )
+    return subprocess.Popen(
+        command,
+        shell=True,
+        cwd=workspace,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        start_new_session=True,
+    )
+
+
+def _run_bash(args: dict[str, Any], session: Session) -> ToolResult:
+    command = str(args.get("command") or "")
+    if not command:
+        return ToolResult.error("'command' is required")
+    try:
+        timeout = int(args.get("timeout", DEFAULT_TIMEOUT) or DEFAULT_TIMEOUT)
+    except (TypeError, ValueError):
+        return ToolResult.error("'timeout' must be an integer")
+    timeout = max(1, min(timeout, MAX_TIMEOUT))
+
+    workspace_root = session.workspace_root
+    remote_argv, remote_warning = wrap_remote_command(
+        command, workspace=workspace_root
+    )
+    prefix: list[str] = []
+    wrapped: str | None = None
+    if remote_argv is not None:
+        argv = remote_argv
+        wrapped = "remote"
+    else:
+        if remote_warning:
+            prefix.append(f"[remote] {remote_warning}")
+        argv, sandbox_warning = wrap_command(command, workspace=workspace_root)
+        if argv != [*_FALLBACK_ARGV, command]:
+            wrapped = "sandbox"
+        if sandbox_warning:
+            prefix.append(f"[sandbox] {sandbox_warning}")
+
+    workspace = str(workspace_root)
+    try:
+        proc = _popen(
+            command, argv=argv if wrapped else None, workspace=workspace
+        )
+    except OSError as exc:
+        if wrapped is None:
+            return ToolResult.error(f"Failed to start command: {exc}")
+        # The wrapper exists on PATH but could not start; keep the tool usable.
+        kind = "remote" if wrapped == "remote" else "sandbox"
+        fallback = "running locally" if kind == "remote" else "running unsandboxed"
+        prefix.append(
+            f"[{kind}] failed to start the {kind} command ({exc}); {fallback}"
+        )
+        try:
+            proc = _popen(command, argv=None, workspace=workspace)
+        except OSError as exc2:
+            return ToolResult.error(f"Failed to start command: {exc2}")
+
+    try:
+        stdout, stderr = proc.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        # start_new_session=True put the shell (and its children) in their own
+        # process group, so killpg takes down the whole tree.
+        try:
+            os.killpg(os.getpgid(proc.pid), signal.SIGKILL)
+        except (ProcessLookupError, PermissionError):
+            pass
+        try:
+            proc.communicate(timeout=5)
+        except subprocess.TimeoutExpired:
+            pass
+        return ToolResult.error(f"Command timed out after {timeout}s")
+
+    parts = list(prefix)
+    if stdout:
+        parts.append(_truncate(stdout))
+    if stderr:
+        parts.append("[stderr]\n" + _truncate(stderr))
+    parts.append(f"[exit code: {proc.returncode}]")
+    return ToolResult(content="\n".join(parts), ok=proc.returncode == 0)
+
+
+run_bash_tool = FunctionTool(
+    name="run_bash",
+    description=(
+        "Run a shell command in the workspace root and return its stdout, "
+        "stderr, and exit code. Use for builds, tests, git, etc."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "command": {
+                "type": "string",
+                "description": "The shell command to execute.",
+            },
+            "timeout": {
+                "type": "integer",
+                "description": "Timeout in seconds (default 120, max 3600).",
+            },
+        },
+        "required": ["command"],
+    },
+    func=_run_bash,
+    runs=True,
+)

kiwimatecoder/tools/search.py

@@ -0,0 +1,224 @@
+"""search tool: grep-style content search and glob-style filename search."""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+import re
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Any
+
+from kiwimatecoder.session import Session
+from kiwimatecoder.tools.base import FunctionTool, ToolResult
+from kiwimatecoder.tools.paths import (
+    PathError,
+    display_path,
+    get_workspace_ignore,
+    resolve_in_workspace,
+)
+
+MAX_MATCHES = 200
+DEFAULT_SEMANTIC_HITS = 10
+MAX_SEMANTIC_HITS = 50
+
+
+def _iter_files(root: Path, session: Session, glob_pattern: str | None = None) -> Iterator[Path]:
+    ignore = get_workspace_ignore(session.workspace_root)
+    for dirpath, dirnames, filenames in os.walk(root, topdown=True, followlinks=False):
+        dir_p = Path(dirpath)
+        dirnames[:] = [
+            d for d in dirnames
+            if not ignore.is_ignored(dir_p / d, is_dir=True)
+        ]
+        dirnames.sort()
+        for f in sorted(filenames):
+            file_p = dir_p / f
+            if ignore.is_ignored(file_p, is_dir=False):
+                continue
+            if glob_pattern:
+                rel = display_path(file_p, session.workspace_root)
+                if not fnmatch.fnmatch(f, glob_pattern) and not fnmatch.fnmatch(
+                    rel, glob_pattern
+                ):
+                    continue
+            yield file_p
+
+
+def _glob_search(root: Path, pattern: str, session: Session) -> list[str]:
+    ignore = get_workspace_ignore(session.workspace_root)
+    results: list[str] = []
+    for dirpath, dirnames, filenames in os.walk(root, topdown=True, followlinks=False):
+        dir_p = Path(dirpath)
+        dirnames[:] = [
+            d for d in dirnames
+            if not ignore.is_ignored(dir_p / d, is_dir=True)
+        ]
+        dirnames.sort()
+        for name in sorted(filenames + dirnames):
+            p = dir_p / name
+            is_dir = name in dirnames
+            if ignore.is_ignored(p, is_dir=is_dir):
+                continue
+            rel = display_path(p, session.workspace_root)
+            if fnmatch.fnmatch(name, pattern) or fnmatch.fnmatch(rel, pattern):
+                results.append(rel)
+                if len(results) >= MAX_MATCHES:
+                    return results
+    return results
+
+
+def _grep_search(
+    root: Path, pattern: str, glob: str | None, session: Session
+) -> list[str]:
+    try:
+        regex = re.compile(pattern)
+    except re.error as exc:
+        raise ValueError(f"Invalid regex: {exc}") from exc
+
+    results: list[str] = []
+    for p in _iter_files(root, session, glob):
+        try:
+            data = p.read_bytes()
+        except OSError:
+            continue
+        if b"\x00" in data[:1024]:
+            continue
+        rel = display_path(p, session.workspace_root)
+        for lineno, line in enumerate(data.decode("utf-8", "replace").splitlines(), 1):
+            if regex.search(line):
+                results.append(f"{rel}:{lineno}: {line.strip()}")
+                if len(results) >= MAX_MATCHES:
+                    return results
+    return results
+
+
+def _semantic_search(
+    root: Path, query: str, args: dict[str, Any], session: Session
+) -> list[str]:
+    """Rank the workspace index against ``query`` and format the hits.
+
+    The index is refreshed incrementally first (and auto-built on first use).
+    Indexing failures are converted to ``ValueError`` so the tool returns a
+    friendly error instead of raising.
+    """
+    from kiwimatecoder import config
+    from kiwimatecoder.index import builder, search as index_search
+
+    try:
+        if not config.get_index()["enabled"]:
+            raise ValueError(
+                "Codebase indexing is disabled. Set "
+                '"index": {"enabled": true} in the config to use mode=\'semantic\'.'
+            )
+        builder.build_index(session.workspace_root)
+        limit_value = args.get("limit")
+        try:
+            limit = (
+                int(limit_value)
+                if limit_value is not None
+                else DEFAULT_SEMANTIC_HITS
+            )
+        except (TypeError, ValueError) as exc:
+            raise ValueError("'limit' must be an integer") from exc
+        limit = max(1, min(limit, MAX_SEMANTIC_HITS))
+        hits = index_search.search_index(
+            query, limit=limit, workspace_root=session.workspace_root
+        )
+    except ValueError:
+        raise
+    except Exception as exc:  # indexing must never crash a tool call
+        raise ValueError(f"Semantic search failed: {exc}") from exc
+
+    workspace = session.workspace_root.resolve()
+    prefix = ""
+    if root != workspace:
+        try:
+            prefix = root.relative_to(workspace).as_posix() + "/"
+        except ValueError as exc:
+            raise ValueError("The search path is outside the workspace.") from exc
+    results: list[str] = []
+    for hit in hits:
+        if prefix and not hit.path.startswith(prefix):
+            continue
+        results.append(f"{hit.path}:{hit.start_line}: {hit.snippet}")
+    return results
+
+
+def _search(args: dict[str, Any], session: Session) -> ToolResult:
+    pattern = str(args.get("pattern") or "")
+    if not pattern:
+        return ToolResult.error("'pattern' is required")
+    mode = str(args.get("mode", "grep") or "grep")
+    path = str(args.get("path", ".") or ".")
+    try:
+        root = resolve_in_workspace(path, session.workspace_root)
+    except PathError as exc:
+        return ToolResult.error(str(exc))
+    if not root.is_dir():
+        return ToolResult.error(f"'{path}' is not a directory")
+
+    try:
+        if mode == "semantic":
+            results = _semantic_search(root, pattern, args, session)
+        elif mode == "glob":
+            results = _glob_search(root, pattern, session)
+        else:
+            glob_arg = args.get("glob")
+            glob_val = str(glob_arg) if glob_arg is not None else None
+            results = _grep_search(root, pattern, glob_val, session)
+    except ValueError as exc:
+        return ToolResult.error(str(exc))
+
+    if not results:
+        return ToolResult(content="No matches found.")
+    header = ""
+    if len(results) >= MAX_MATCHES:
+        header = f"[showing first {MAX_MATCHES} matches]\n"
+    return ToolResult(content=header + "\n".join(results))
+
+
+search_tool = FunctionTool(
+    name="search",
+    description=(
+        "Search the workspace. mode='grep' finds a regex in file contents "
+        "(optionally filtered by a glob); mode='glob' finds files by name "
+        "pattern (e.g. '**/*.py'); mode='semantic' ranks files against a "
+        "natural-language query using the local codebase index (auto-built and "
+        "refreshed incrementally) and returns paths, line numbers, and "
+        "snippets."
+    ),
+    parameters={
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": (
+                    "Regex (grep mode), filename glob (glob mode), or a "
+                    "natural-language query (semantic mode)."
+                ),
+            },
+            "mode": {
+                "type": "string",
+                "enum": ["grep", "glob", "semantic"],
+                "description": "Search mode. Defaults to grep.",
+            },
+            "path": {
+                "type": "string",
+                "description": "Directory to search in. Defaults to workspace root.",
+            },
+            "glob": {
+                "type": "string",
+                "description": "Optional filename glob to restrict grep (e.g. '**/*.py').",
+            },
+            "limit": {
+                "type": "integer",
+                "description": (
+                    "Maximum semantic hits to return (default 10, max 50)."
+                ),
+            },
+        },
+        "required": ["pattern"],
+    },
+    func=_search,
+)