python-agent-harness 1.5.0__py3-none-any.whl

python_agent_harness/tools/edit.py

@@ -0,0 +1,272 @@
+"""Edit tool: string replacement and diff/patch modes.
+
+Edit mirrors `gptel-agent--edit-files` (inherited unchanged by the
+harness): a string-replacement mode (exact unique `old_str` → `new_str`,
+single files only) and a diff/patch mode that shells out to
+`patch --forward` and works on both single files and whole directories
+(multi-file unified diffs), with ```diff code-fence removal and
+hunk-header line-count fixing.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+
+from ..diffrender import unified_diff
+from .base import Tool, ToolContext
+
+
+class Edit(Tool):
+    name = "Edit"
+    description = (
+        "Replace text in one or more files.\n\n"
+        "To edit a single file, provide the file `path`.\n\n"
+        "For the replacement, there are two methods:\n"
+        "- Short replacements: Provide both `old_str` and `new_str`, in which "
+        "case `old_str` needs to exactly match one unique section of the "
+        "original file, including any whitespace.  Make sure to include "
+        "enough context that the match is not ambiguous.  The entire original "
+        "string will be replaced with `new_str`.\n"
+        "- Long or involved replacements: set the `diff` parameter to true and "
+        "provide a unified diff in `new_str`. `old_str` can be ignored.\n\n"
+        "To edit multiple files,\n"
+        "- provide the directory path,\n"
+        "- set the `diff` parameter to true\n"
+        "- and provide a unified diff in `new_str`.\n\n"
+        "Diff instructions:\n"
+        "- The diff must be in unified format (optionally within a ```diff "
+        "fenced code block).\n"
+        "- The file paths within the diff (e.g. '--- a/filename' "
+        "'+++ b/filename') must be appropriate for the `path`.\n\n"
+        'To simply insert text at some line, use the "Insert" tool instead.'
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "path": {"type": "string", "description": "File path or directory to edit"},
+            "old_str": {
+                "type": "string",
+                "description": "Original string to replace.  If providing a unified diff, this should be false",
+            },
+            "new_str": {"type": "string", "description": "Replacement string OR unified diff text"},
+            "diff": {
+                "type": "boolean",
+                "description": "Whether the replacement is a string or a diff.  `true` for a diff, `false` otherwise.",
+            },
+        },
+        "required": ["path", "new_str"],
+    }
+
+    def run(self, args: dict, ctx: ToolContext) -> str:
+        raw = args["path"]
+        path = os.path.realpath(os.path.abspath(raw))
+        if not os.access(path, os.R_OK):
+            return f"Error: File or directory {path} is not readable"
+        new_str = args.get("new_str")
+        if new_str is None:
+            return "Error: Required argument `new_str' missing"
+        old = args.get("old_str")
+        diffp = args.get("diff")
+        # gptel: string mode when `diff` is false OR `old_str` is provided.
+        if diffp is False or old is not None:
+            return self._string_replace(path, old, new_str, ctx)
+        # Diff mode runs `patch` in Emacs `file-name-directory' of the path:
+        # a trailing-slash directory path -> that directory itself, so a
+        # multi-file diff applies to files within it; otherwise the parent.
+        if raw.endswith("/") or raw.endswith(os.sep):
+            cwd = path or "/"
+        else:
+            cwd = os.path.dirname(path) or "/"
+        return self._apply_patch(path, cwd, new_str, ctx)
+
+    def _string_replace(self, path: str, old: str | None, new_str: str, ctx: ToolContext) -> str:
+        if os.path.isdir(path):
+            return (
+                f"Error: String replacement is intended for single files, not directories ({path})"
+            )
+        if old is None:
+            return "Error: old_str is required for non-diff edits"
+        try:
+            with open(path, encoding="utf-8") as f:
+                content = f.read()
+        except OSError as e:
+            return f"Error: cannot read {path}: {e}"
+        count = content.count(old)
+        if count == 0:
+            return f'Error: Could not find old_str "{old[:20]}" in file {path}'
+        if count > 1:
+            return (
+                "Error: Match is not unique. Consider providing more context "
+                "for the replacement, or a unified diff"
+            )
+        new = content.replace(old, new_str, 1)
+        try:
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(new)
+        except OSError as e:
+            return f"Error: {e}"
+        diff_text = unified_diff(content, new, path)
+        if diff_text:
+            ctx.record_diff(diff_text)
+        return f"Successfully replaced {old[:20]} (truncated) with {new_str[:20]} (truncated)"
+
+    def _apply_patch(self, path: str, cwd: str, diff: str, ctx: ToolContext) -> str:
+        """Diff/patch mode: shell out to `patch --forward` (files or dirs).
+
+        Mirrors the diff branch of `gptel-agent--edit-files`: ensure a
+        trailing newline, strip a ```diff code fence, fix hunk-header line
+        counts, then run `patch` in CWD (Emacs `file-name-directory' of the
+        path).  For a single file the before/after contents are captured to
+        record a diff for the UI; directory (multi-file) patches skip that.
+        """
+        if not shutil.which("patch"):
+            return (
+                'Error: Command "patch" not available, cannot apply diffs. '
+                "Use string replacement instead"
+            )
+        text = diff if diff.endswith("\n") else diff + "\n"
+        text = _strip_diff_fence(text)
+        text = _fix_patch_headers(text)
+        is_file = os.path.isfile(path)
+        old_content = None
+        if is_file:
+            try:
+                with open(path, encoding="utf-8", errors="replace") as f:
+                    old_content = f.read()
+            except OSError:
+                old_content = None
+        options = ["--forward", "--verbose"]
+        try:
+            proc = subprocess.run(
+                ["patch", *options],
+                input=text,
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=60,
+            )
+        except (OSError, subprocess.TimeoutExpired) as e:
+            return f"Error: {e}"
+        out = (proc.stdout or "") + (proc.stderr or "")
+        if proc.returncode != 0:
+            return (
+                f"Error: Failed to apply diff to {path} (exit status "
+                f"{proc.returncode}).\nPatch command options: {options}\n"
+                f"Patch STDOUT:\n{out}"
+            )
+        if old_content is not None and os.path.isfile(path):
+            try:
+                with open(path, encoding="utf-8", errors="replace") as f:
+                    new_content = f.read()
+                diff_text = unified_diff(old_content, new_content, path)
+                if diff_text:
+                    ctx.record_diff(diff_text)
+            except OSError:
+                pass
+        return (
+            f"Diff successfully applied to {path}.\n"
+            f"Patch command options: {options}\n"
+            f"Patch STDOUT:\n{out}"
+        )
+
+
+_HUNK_HEADER_RE = re.compile(r"^@@ -(\d+),(\d+) +\+(\d+),(\d+) @@")
+# A file section's header pair: the marker must be followed by whitespace
+# (real headers name a path), which content lines rendered ---/+++ by the
+# diff itself normally are not.
+_FILE_HEADER_OLD_RE = re.compile(r"^---[ \t]")
+_FILE_HEADER_NEW_RE = re.compile(r"^\+\+\+[ \t]")
+
+
+def _strip_diff_fence(text: str) -> str:
+    """Remove a leading ```diff fence and its trailing ``` line.
+
+    Mirrors the fence handling in `gptel-agent--edit-files`: only a
+    ```diff opening fence is stripped (a bare ``` or ```patch is left
+    for `patch` to reject), together with the closing ``` line.
+    """
+    lines = text.splitlines(keepends=True)
+    if lines and re.match(r"^ *```diff", lines[0]):
+        lines = lines[1:]
+        if lines and re.match(r"^ *```", lines[-1]):
+            lines = lines[:-1]
+        return "".join(lines)
+    return text
+
+
+def _fix_patch_headers(diff_text: str) -> str:
+    """Recompute the line counts in unified-diff hunk headers.
+
+    Mirrors `gptel-agent--fix-patch-headers`: for every ``@@ -a,b +c,d @@``
+    header, recount the body (context/removed/added lines) up to the next
+    header or EOF and rewrite ``b`` and ``d`` accordingly, so a model that
+    miscounts hunk lengths still produces a patch `patch` will accept.
+    Headers without explicit counts are passed through untouched.
+    """
+    lines = diff_text.splitlines(keepends=True)
+    out: list[str] = []
+    i = 0
+    n = len(lines)
+    while i < n:
+        m = _HUNK_HEADER_RE.match(lines[i])
+        if not m:
+            out.append(lines[i])
+            i += 1
+            continue
+        orig_line, new_line = int(m.group(1)), int(m.group(3))
+        j = i + 1
+        orig_count = new_count = 0
+        body: list[str] = []
+        while j < n and not lines[j].startswith("@@"):
+            line = lines[j]
+            if line.startswith("---") and _starts_file_section(lines, j):
+                # A ---/+++ pair introducing the next file; not hunk body.
+                break
+            if line.startswith("-"):
+                orig_count += 1
+            elif line.startswith("+"):
+                new_count += 1
+            elif line.startswith(" "):
+                orig_count += 1
+                new_count += 1
+            body.append(line)
+            j += 1
+        out.append(f"@@ -{orig_line},{orig_count} +{new_line},{new_count} @@\n")
+        out.extend(body)
+        i = j
+    return "".join(out)
+
+
+def _starts_file_section(lines: list[str], idx: int) -> bool:
+    """Whether lines[idx] begins the next file's ---/+++ header pair.
+
+    A new file section in a multi-file diff is ``--- path`` immediately
+    followed by ``+++ path`` and then a hunk header.  Removed/added
+    content lines whose text merely starts with ``--``/``++`` (rendered
+    ``---``/``+++``) are hunk body and must be counted, so all three
+    parts are required:
+
+    * the ordered pair — a lone ``---``-rendered content line as a
+      hunk's LAST body line is followed directly by the next hunk
+      header, which a peek for a trailing ``@@`` alone cannot tell from
+      a file header (it silently dropped the line from the count and
+      made `patch` reject the whole diff);
+    * the space/tab after the marker — real headers carry a path
+      (``--- a/f``), content lines usually do not (``---removed``);
+    * the trailing hunk header.
+
+    A hunk whose last two body lines happen to be a removed line
+    starting with ``-- `` AND an added line starting with ``++ `` is
+    still indistinguishable from a file header pair by shape alone; it
+    stays a known (and far rarer) miscount.
+    """
+    if not _FILE_HEADER_OLD_RE.match(lines[idx]):
+        return False
+    if idx + 1 >= len(lines) or not _FILE_HEADER_NEW_RE.match(lines[idx + 1]):
+        return False
+    return idx + 2 < len(lines) and lines[idx + 2].startswith("@@")

python_agent_harness/tools/filesystem.py

@@ -0,0 +1,180 @@
+"""Filesystem tool helpers and compatibility re-exports.
+
+This module hosts the SHARED helper machinery for the filesystem
+tools — spooling oversized tool results to temp files
+(`gptel-agent--truncate-buffer` parity), git-root detection, and the
+``natnump`` predicate — and re-exports the tool classes that live in
+per-tool modules (`read.py`, `glob.py`, `grep.py`, `edit.py`,
+`write.py`, `insert.py`, `mkdir.py`), so existing imports such as
+``from .tools.filesystem import Read`` keep working.
+
+The helpers must stay defined HERE (not in a separate ``_common``
+module): tests monkey-patch ``filesystem._spool_dir`` and read
+``filesystem.MAX_OUTPUT`` / ``SPOOL_LINES`` / ``READ_SIZE_LIMIT`` off
+this module's namespace, and the helper functions resolve them through
+their defining module's globals.
+
+NOTE: these filesystem tools are intentionally SYNCHRONOUS.  Only Bash
+and Agent are `:async t` in gptel-agent; sync tools run one at a time in
+the model-emitted order.  Do NOT be tempted to port every tool to async
+for parallelism: tools can depend on one another's side effects within a
+single round (e.g. Write/Mkdir then Read/Edit the same path, or Edit then
+Grep the just-changed file).  Running them concurrently would introduce
+read-after-write races and non-deterministic results.  Keep filesystem
+tools synchronous so ordering — and therefore correctness — is preserved.
+
+Oversized Glob/Grep results are spilled to a temp file (mirroring
+`gptel-agent--truncate-buffer` in gptel-agent-tools.el): the tool
+result then carries a short preview plus the temp-file path, so the
+full output remains readable via the Read tool.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil  # noqa: F401  (mock target for tests)
+import subprocess  # noqa: F401  (mock target for tests)
+import tempfile
+import time
+from pathlib import Path
+from typing import TypeGuard
+
+from ..config import MAX_OUTPUT_CHARS as MAX_OUTPUT
+
+SPOOL_LINES = 50  # preview lines kept when results are spilled
+READ_SIZE_LIMIT = 400 * 1024  # whole-file reads above this are refused
+# (mirrors gptel-agent-read-file-size-threshold)
+
+_spooled_files: list[str] = []  # temp files created by _spool, cleaned
+# up by cleanup_spooled_files on session close
+
+
+def _truncate(text: str, label: str = "output") -> str:
+    """In-memory truncation fallback (used when spooling to disk fails)."""
+    if len(text) > MAX_OUTPUT:
+        return text[:MAX_OUTPUT] + f"\n... [truncated {label}]"
+    return text
+
+
+def _spool_dir() -> str:
+    """Reliable temp dir for spilled results (first candidate set, else /tmp)."""
+    for d in (
+        os.environ.get("TMPDIR"),
+        os.environ.get("TMP"),
+        os.environ.get("TEMP"),
+        tempfile.gettempdir(),
+    ):
+        if d:
+            return os.path.abspath(d)
+    return "/tmp"
+
+
+def _spool(text: str, label: str) -> str:
+    """Spill oversized tool output to a temp file; return a preview.
+
+    Mirrors `gptel-agent--truncate-buffer': when TEXT exceeds
+    MAX_OUTPUT chars the full content is written to a temp file and the
+    returned string becomes a header (size + path), the first
+    SPOOL_LINES lines, and a footer telling the agent to Read the file.
+    Falls back to in-memory truncation if the temp file cannot be
+    written."""
+    if len(text) <= MAX_OUTPUT:
+        return text
+    stamp = time.strftime("%Y%m%d-%H%M%S")
+    try:
+        fd, temp_file = tempfile.mkstemp(
+            prefix=f"python-agent-harness-{label}-{stamp}-",
+            suffix=".txt",
+            dir=_spool_dir(),
+        )
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(text)
+        _spooled_files.append(temp_file)
+    except OSError:
+        return _truncate(text, label)
+    lines = text.splitlines()
+    preview = "\n".join(lines[:SPOOL_LINES])
+    return (
+        f"{label} results too large ({len(text)} chars, {len(lines)} lines) "
+        f"for context window.\n"
+        f"Stored in: {temp_file}\n\n"
+        f"First {SPOOL_LINES} lines:\n\n"
+        f"{preview}\n\n"
+        f'[Use Read tool with file_path="{temp_file}" to view full results]'
+    )
+
+
+def cleanup_spooled_files() -> None:
+    """Delete all tracked spooled temp files (best effort).
+
+    Mirrors ``PlanMode.cleanup_plan_file``: called from
+    ``Session.close`` so oversized tool results do not accumulate
+    in the temp dir.  Files already removed (e.g. by a restored
+    session) are skipped.
+    """
+    paths = _spooled_files[:]
+    _spooled_files.clear()
+    for path in paths:
+        try:
+            if os.path.exists(path):
+                os.remove(path)
+        except OSError:
+            pass
+
+
+def _natnump(n: object) -> TypeGuard[int]:
+    """True for a non-negative integer (Emacs `natnump' semantics)."""
+    return isinstance(n, int) and not isinstance(n, bool) and n >= 0
+
+
+def _git_root(path: str) -> str | None:
+    d = Path(path).resolve()
+    for parent in [d, *d.parents]:
+        # .git is a directory in a normal clone and a file in worktrees
+        # / submodules; exists() covers both.
+        if (parent / ".git").exists():
+            return str(parent)
+    return None
+
+
+# ---------------------------------------------------------------------------
+# tool classes live in per-tool modules; re-exported here so existing
+# `from .tools.filesystem import ...` imports (tests included) keep working.
+# The imports sit at the BOTTOM on purpose: the per-tool modules import the
+# shared helpers from this module, so the helpers above must be defined
+# before those modules are loaded (this is the fixed import order — do not
+# move these imports to the top of the file).
+# ---------------------------------------------------------------------------
+# isort: off
+from .edit import Edit, _fix_patch_headers, _strip_diff_fence  # noqa: E402
+from .glob import GlobTool, _git_glob_results  # noqa: E402
+from .grep import Grep, _grep_out  # noqa: E402
+from .insert import Insert  # noqa: E402
+from .mkdir import Mkdir  # noqa: E402
+from .read import Read  # noqa: E402
+from .write import Write  # noqa: E402
+# isort: on
+
+__all__ = [
+    "Edit",
+    "GlobTool",
+    "Grep",
+    "Insert",
+    "Mkdir",
+    "Read",
+    "Write",
+    "MAX_OUTPUT",
+    "READ_SIZE_LIMIT",
+    "SPOOL_LINES",
+    "cleanup_spooled_files",
+    "_fix_patch_headers",
+    "_git_glob_results",
+    "_git_root",
+    "_grep_out",
+    "_natnump",
+    "_spool",
+    "_spool_dir",
+    "_spooled_files",
+    "_strip_diff_fence",
+    "_truncate",
+]

python_agent_harness/tools/glob.py

@@ -0,0 +1,161 @@
+"""Glob tool: `git ls-files` inside git repos, `tree` outside.
+
+Glob mirrors `gptel-agent-harness-tools--glob`: inside a git
+repository it uses `git ls-files` (fast, .gitignore-respecting), and
+falls back to the `tree` command outside git.  Oversized results are
+spilled to a temp file (see `filesystem._spool`), so no matches are
+ever silently lost.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+from .base import Tool, ToolContext
+from .filesystem import _git_root, _natnump, _spool
+
+
+class GlobTool(Tool):
+    name = "Glob"
+    description = (
+        "Recursively find files matching a provided glob pattern.\n\n"
+        '- Supports glob patterns like "*.md" or "*test*.py".\n'
+        "- Inside a git repository, matching respects .gitignore and covers "
+        "both tracked and untracked files.\n"
+        "- Returns matching file paths (absolute) at all depths.  Limit the "
+        "depth of the search by providing the `depth` argument.\n"
+        "- When you are doing an open ended search that may require multiple "
+        'rounds of globbing and grepping, use the "Agent" tool instead.\n'
+        "- Oversized results are spilled to a temp file (see the 'Stored in:' "
+        "path); use Read to view the full output."
+    )
+    parameters = {
+        "type": "object",
+        "properties": {
+            "pattern": {
+                "type": "string",
+                "description": (
+                    'Glob pattern to match, for example "*.el". Must not be '
+                    'empty.\nUse "*" to list all files in a directory.'
+                ),
+            },
+            "path": {
+                "type": "string",
+                "description": (
+                    'Directory to search in.  Supports relative paths and defaults to "."'
+                ),
+            },
+            "depth": {
+                "type": "integer",
+                "description": (
+                    "Limit directory depth of search, 1 or higher. Defaults to no limit."
+                ),
+            },
+        },
+        "required": ["pattern"],
+    }
+
+    def run(self, args: dict, ctx: ToolContext) -> str:
+        # Mirrors `gptel-agent-harness-tools--glob': `git ls-files' inside a
+        # git repository (fast, .gitignore-respecting), `tree' as a fallback
+        # outside git.
+        pattern = args.get("pattern") or ""
+        if not pattern:
+            return "Error: pattern must not be empty"
+        path = args.get("path")
+        if path:
+            if not (os.path.isdir(path) and os.access(path, os.R_OK)):
+                return f"Error: path {path} is not readable"
+        else:
+            path = ctx.cwd
+        base = os.path.abspath(path)  # directory-file-name + expand-file-name
+        depth = args.get("depth")
+
+        git_root = _git_root(base)
+        if not git_root and not shutil.which("tree"):
+            return "Error: Executable `tree` not found.  This tool cannot be used"
+
+        if git_root:
+            rel = os.path.relpath(base, git_root)
+            pathspec = pattern if rel == "." else f"{rel}/{pattern}".replace(os.sep, "/")
+            try:
+                proc = subprocess.run(
+                    [
+                        "git",
+                        "ls-files",
+                        "-z",
+                        "--full-name",
+                        "--cached",
+                        "--others",
+                        "--exclude-standard",
+                        "--",
+                        pathspec,
+                    ],
+                    cwd=git_root,
+                    capture_output=True,
+                    text=True,
+                    encoding="utf-8",
+                    errors="replace",
+                    timeout=60,
+                )
+            except (OSError, subprocess.TimeoutExpired) as e:
+                return f"Error: {e}"
+            if proc.returncode != 0:
+                # Failure banner is prepended to whatever git emitted.
+                banner = f"Glob failed with exit code {proc.returncode}\n.STDOUT:\n\n"
+                return _spool(banner + (proc.stdout or "") + (proc.stderr or ""), "glob")
+            return _git_glob_results(proc.stdout, git_root, base, depth)
+
+        # --- Tree strategy (fallback outside git) ---
+        cmd = [
+            "tree",
+            "-l",
+            "-f",
+            "-i",
+            "-I",
+            ".git",
+            "--sort=mtime",
+            "--ignore-case",
+            "--prune",
+            "-P",
+            pattern,
+            base,
+        ]
+        if _natnump(depth):
+            cmd += ["-L", str(depth)]
+        try:
+            proc = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=60,
+            )
+        except (OSError, subprocess.TimeoutExpired) as e:
+            return f"Error: {e}"
+        out = proc.stdout
+        if proc.returncode != 0:
+            out = f"Glob failed with exit code {proc.returncode}\n.STDOUT:\n\n" + out
+        return _spool(out, "glob")
+
+
+def _git_glob_results(raw: str, git_root: str, base: str, depth: object) -> str:
+    """Format `git ls-files -z` output into absolute paths, depth-filtered.
+
+    Mirrors the git branch of `gptel-agent-harness-tools--glob': split on
+    NUL, drop entries whose slash-count reaches ``base_depth + depth``
+    (only when DEPTH is a non-negative integer — `natnump'), then prefix
+    each remaining entry with GIT-ROOT.
+    """
+    lines = [line for line in raw.split("\0") if line]
+    if _natnump(depth):
+        rel_base = os.path.relpath(base, git_root)
+        base_depth = 0 if rel_base == "." else 1 + rel_base.count("/")
+        lines = [line for line in lines if line.count("/") < base_depth + depth]
+    out = "\n".join(os.path.join(git_root, line) for line in lines)
+    if not out:
+        return ""
+    return _spool(out + "\n", "glob")