py-harness-cli 0.3.0__py3-none-any.whl

harness/act/patch_fix.py

@@ -0,0 +1,138 @@
+"""Match a `Find:` block against a file, and explain a failed match.
+
+`patch` replaces an exact substring. Exact matching is deliberate: it fails
+instead of editing a line the user did not mean. The cost is that a small
+model, which often reproduces the words of a line but not its indentation,
+gets no way forward when the match fails.
+
+These functions add two recoveries that do not weaken the guarantee:
+
+* Retry the match ignoring differences in whitespace only. If that matches
+  in exactly one place, use it. If it matches in more than one place, the
+  match is rejected rather than guessed.
+* When there is still no match, return the lines in the file that are most
+  similar, so the next attempt can copy a real line.
+"""
+
+from __future__ import annotations
+
+import difflib
+import re
+from dataclasses import dataclass
+
+MAX_SUGGESTIONS = 3
+MIN_RATIO = 0.6
+
+
+def normalize(line: str) -> str:
+    return re.sub(r"\s+", " ", line).strip()
+
+
+@dataclass(frozen=True)
+class Match:
+    text: str
+    exact: bool
+
+
+def _windows(lines: list[str], size: int) -> list[tuple[int, int]]:
+    return [(i, i + size) for i in range(0, len(lines) - size + 1)]
+
+
+def find_match(text: str, find: str) -> Match | None:
+    """Find where `find` occurs in `text`.
+
+    Returns the exact text to replace, and whether it matched exactly.
+    Returns None when there is no match, or when a whitespace-insensitive
+    match occurs in more than one place.
+    """
+    if not find:
+        return None
+    hits = text.count(find)
+    if hits == 1:
+        return Match(find, True)
+    if hits > 1:
+        return None
+    wanted = [normalize(line) for line in find.strip("\n").splitlines()]
+    if not wanted or not any(wanted):
+        return None
+    lines = text.splitlines()
+    if len(wanted) > len(lines):
+        return None
+    found: list[str] = []
+    for start, end in _windows(lines, len(wanted)):
+        if [normalize(line) for line in lines[start:end]] == wanted:
+            found.append("\n".join(lines[start:end]))
+            if len(found) > 1:
+                return None
+    if len(found) != 1:
+        return None
+    return Match(found[0], False)
+
+
+def suggestions(text: str, find: str, *, limit: int = MAX_SUGGESTIONS) -> list[str]:
+    """Return the lines in `text` most similar to `find`, for an error message.
+
+    Each entry is formatted as "line number: line content".
+    """
+    head = normalize(find.strip("\n").splitlines()[0]) if find.strip() else ""
+    if not head:
+        return []
+    scored: list[tuple[float, int, str]] = []
+    for number, line in enumerate(text.splitlines(), 1):
+        candidate = normalize(line)
+        if not candidate:
+            continue
+        ratio = difflib.SequenceMatcher(None, head, candidate).ratio()
+        if ratio >= MIN_RATIO:
+            scored.append((ratio, number, line.rstrip()))
+    scored.sort(key=lambda item: (-item[0], item[1]))
+    if scored:
+        return [f"{number}: {line}" for _ratio, number, line in scored[:limit]]
+    return _same_opener(text, head, limit)
+
+
+def _same_opener(text: str, head: str, limit: int) -> list[str]:
+    """Nothing scored. Show lines that at least start the same way."""
+    first = head.split(" ", 1)[0]
+    if not first:
+        return []
+    out: list[str] = []
+    for number, line in enumerate(text.splitlines(), 1):
+        if normalize(line).startswith(first):
+            out.append(f"{number}: {line.rstrip()}")
+        if len(out) >= limit:
+            break
+    return out
+
+
+def miss_message(text: str, find: str) -> str:
+    close = suggestions(text, find)
+    if not close:
+        return (
+            "Find: string not in file. Action: read that Path: first, "
+            "then copy one whole line from it."
+        )
+    listed = "\n".join(f"  {item}" for item in close)
+    return (
+        "Find: string not in file. Closest lines in this file — copy one "
+        f"whole line verbatim:\n{listed}"
+    )
+
+
+def align_indent(matched: str, replace: str) -> str:
+    """Give `replace` the leading whitespace of the line it will replace.
+
+    A small model often reproduces a line without its indentation. If the
+    replacement has no leading whitespace and the matched text does, the
+    replacement is indented to match.
+    """
+    if not matched or not replace.strip():
+        return replace
+    first = matched.splitlines()[0]
+    indent = first[: len(first) - len(first.lstrip())]
+    if not indent:
+        return replace
+    lines = replace.splitlines()
+    if lines[0].startswith((" ", "\t")):
+        return replace
+    return "\n".join(indent + line if line.strip() else line for line in lines)

harness/act/tools.py

@@ -0,0 +1,244 @@
+"""The seven things the agent can do to a project.
+
+Look for a file, search inside files, read one, run one, change one, and
+draw the shape of the whole. Nothing here decides whether a change is
+allowed — `act.gate` answers that, and `patch_py` and `edit_py` ask it
+before they write.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from harness.act.autofix import (
+    append_instead_of_replacing,
+    apply_function_rename,
+    apply_missing_imports,
+    apply_typo_fixes,
+)
+from harness.act.code import apply_source, read_project_file, resolve_project_file
+from harness.act.gate import (
+    already_defined,
+    refuse_duplicate_module,
+    refuse_missing_import_target,
+    repair_unittest_append,
+    first_refusal,
+)
+from harness.paths import is_secret_name, rel_posix, suffix_globs
+from harness.act.patch_fix import align_indent, find_match, miss_message
+from harness.skillkit.refuse_change import (
+    refuse_add_opens_file,
+    refuse_layout,
+    refuse_ops_draft,
+    refuse_platform_draft,
+    refuse_rename_incomplete,
+    refuse_shell_fetch,
+    refuse_stdlib_shadow,
+    refuse_stub_body,
+    refuse_test_in_impl,
+    refuse_undefined_draft,
+    refuse_weak_test,
+)
+
+from harness.task import looks_like_bugfix, looks_like_fix_smell, rename_pair
+from harness.scan.project_brief import render_map, resolve_scope
+from harness.scan.project_scan import SKIP_DIR
+from harness.scan.repo_map import render_outline
+
+MAX_HITS = 30
+_TRUNC = "\n# … truncated. Narrow Query or pass --scope"
+
+
+def glob_py(project: Path, pattern: str, scope: str = "") -> str:
+    root = project.resolve()
+    base = resolve_scope(project, scope) if scope else root
+    hits: list[str] = []
+    for path in base.glob(pattern):
+        if any(part in SKIP_DIR for part in path.parts):
+            continue
+        if is_secret_name(path.name):
+            continue
+        if path.is_file():
+            hits.append(rel_posix(path, root))
+        if len(hits) >= MAX_HITS:
+            return "\n".join(hits) + _TRUNC
+    if not hits:
+        # rglob if user passed **/...
+        for path in base.rglob(pattern.removeprefix("**/")):
+            if any(part in SKIP_DIR for part in path.parts):
+                continue
+            if is_secret_name(path.name):
+                continue
+            if path.is_file():
+                hits.append(rel_posix(path, root))
+            if len(hits) >= MAX_HITS:
+                return "\n".join(hits) + _TRUNC
+    return "\n".join(hits) or "(no files)"
+
+
+def grep_py(project: Path, query: str, scope: str = "") -> str:
+    root = project.resolve()
+    base = resolve_scope(project, scope) if scope else root
+    try:
+        wanted = re.compile(query)
+    except re.error as exc:
+        return f"bad regex: {exc}"
+    lines: list[str] = []
+    for pattern in suffix_globs():
+        for path in base.rglob(pattern):
+            if any(part in SKIP_DIR for part in path.parts):
+                continue
+            if is_secret_name(path.name):
+                continue
+            try:
+                text = path.read_text(encoding="utf-8")
+            except OSError:
+                continue
+            for i, line in enumerate(text.splitlines(), 1):
+                if wanted.search(line):
+                    rel = rel_posix(path, root)
+                    lines.append(f"{rel}:{i}:{line.strip()[:160]}")
+                    if len(lines) >= MAX_HITS:
+                        return "\n".join(lines) + _TRUNC
+    return "\n".join(lines) or "(no hits)"
+
+
+def map_py(project: Path, scope: str = "") -> str:
+    """File list plus a signature outline. Sizes do not tell it where to look."""
+    return f"{render_map(project, scope)}\n\n{render_outline(project, scope)}"
+
+
+def read_py(project: Path, rel: str, about: str = "") -> str:
+    """The file. `about` names what the read is for, so that a file too
+    long to send whole keeps the part being asked about."""
+    path = resolve_project_file(project, rel)
+    return read_project_file(path, about=about)
+
+
+def patch_py(
+    project: Path,
+    rel: str,
+    find: str,
+    replace: str,
+    append: str = "",
+    task: str = "",
+) -> str:
+    path = resolve_project_file(project, rel)
+    original = path.read_text(encoding="utf-8") if path.is_file() else ""
+    text = original
+    note = ""
+    if looks_like_fix_smell(task):
+        old, new = rename_pair(task)
+        renamed = apply_function_rename(original, old, new)
+        if renamed != original:
+            text = renamed
+            note = " (harness renamed the def)"
+            find = ""
+    if find:
+        if len(find) < 8:
+            return (
+                "Find: must be at least 8 characters. "
+                "Use a unique full line such as: Find: return tota"
+            )
+        hits = text.count(find)
+        if hits > 1:
+            return f"Find: matches {hits} times — use a longer unique snippet"
+        match = find_match(text, find)
+        if match is None:
+            return miss_message(text, find)
+        text = text.replace(
+            match.text,
+            replace if match.exact else align_indent(match.text, replace),
+            1,
+        )
+        if not match.exact:
+            note = " (Find: matched after whitespace normalisation)"
+        else:
+            note = ""
+    elif text == original and not append:
+        return "patch needs Find: or Append:"
+    if append:
+        already = already_defined(original, append, rel)
+        if already:
+            return already
+        repaired = repair_unittest_append(text, append)
+        text = (
+            repaired
+            if repaired is not None
+            else text.rstrip() + "\n\n" + append.rstrip() + "\n"
+        )
+    if looks_like_bugfix(task):
+        bound = apply_typo_fixes(text)
+        if bound != text:
+            text = bound
+            note = (note + " (harness bound unique NameError typo)").strip()
+    repaired = apply_missing_imports(text)
+    if repaired != text:
+        text = repaired
+        note = (note + " (harness added the missing import)").strip()
+    blocked = refuse_duplicate_module(project, rel, original)
+    if not blocked:
+        blocked = refuse_missing_import_target(project, rel, text)
+    if not blocked:
+        blocked = first_refusal(task, rel, original, text, fragment=append or replace)
+    if blocked:
+        return blocked
+    apply_source(path, text, original=original)
+    return (
+        f"patched {rel_posix(path, project.resolve())} "
+        f"(backup {path.name}.bak){note}"
+    )
+
+
+def edit_py(project: Path, rel: str, source: str, task: str = "") -> str:
+    path = resolve_project_file(project, rel)
+    original = path.read_text(encoding="utf-8") if path.is_file() else ""
+    source = apply_missing_imports(source)
+    blocked = refuse_duplicate_module(project, rel, original)
+    if not blocked:
+        blocked = refuse_missing_import_target(project, rel, source)
+    if not blocked:
+        blocked = first_refusal(task, rel, original, source)
+    if blocked:
+        return blocked
+    # A short draft of only-new definitions is an addition, not a rewrite.
+    merged = append_instead_of_replacing(original, source)
+    if merged:
+        apply_source(path, merged, original=original)
+        return (
+            f"appended to {rel_posix(path, project.resolve())} "
+            f"(backup {path.name}.bak) — the draft added new definitions "
+            "rather than replacing the file"
+        )
+    apply_source(path, source, original=original)
+    return f"wrote {rel_posix(path, project.resolve())} (backup {path.name}.bak)"
+
+
+def run_python(project: Path, argv: tuple[str, ...]) -> str:
+    if not argv:
+        return "Argv required, e.g. -m unittest discover -s tests -q"
+    blocked = {"-c", "-m pip", "http.server"}
+    joined = " ".join(argv)
+    if any(tok in joined for tok in blocked) or "|" in joined or ";" in joined:
+        return "refusing that argv"
+    if "unittest" in joined and "tests" in joined and not (project / "tests").is_dir():
+        return "no tests/ directory in this project — add tests/test_*.py first"
+    try:
+        proc = subprocess.run(
+            [sys.executable, *argv],
+            cwd=project,
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+        )
+    except subprocess.TimeoutExpired:
+        return "timed out (60s)"
+    out = (proc.stdout or "") + (proc.stderr or "")
+    return f"exit {proc.returncode}\n{out[-4000:]}"

harness/agent/__init__.py

@@ -0,0 +1,11 @@
+"""The agent loop and its public types.
+
+`Agent` runs one task. `AgentOptions` describes how to run it and
+`AgentResult` describes what happened. Every layer below this one works
+without a model, which is what allows the harness to be tested offline.
+"""
+
+from harness.agent.loop import Agent, Question
+from harness.agent.options import AgentOptions, AgentResult, Step
+
+__all__ = ["Agent", "AgentOptions", "AgentResult", "Question", "Step"]

harness/agent/dispatch.py

@@ -0,0 +1,235 @@
+"""Carry out one action against the project.
+
+Each branch returns the text to show the model and the file path the action
+applied to. The path is kept by the loop so that a later action which does
+not name a file still refers to the file most recently used.
+
+This module makes no decisions about whether an action should run. Those
+decisions are in `harness.agent.policy`.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from pathlib import Path
+
+from harness.act.tools import (
+    edit_py,
+    glob_py,
+    grep_py,
+    map_py,
+    patch_py,
+    read_py,
+    run_python,
+)
+from harness.guard.python_vibe import PythonVibeGuard
+from harness.locate import locate_py
+from harness.scan.layout import render_layout
+from harness.scan.project_brief import resolve_scope
+from harness.ship.git_ship import (
+    commit_changes,
+    create_pr,
+    make_branch,
+    merge_pr,
+    push_branch,
+    read_issue,
+    read_pr,
+)
+from harness.skillkit.catalog import (
+    list_skills,
+    render_catalog,
+    render_skill,
+    skill_from_action,
+)
+
+ACTIONS = (
+    "glob|grep|read|edit|patch|run|map|plan|skill|locate|layout|ask|done|"
+    "issue|branch|commit|push|pr|merge"
+)
+WRITE_ACTIONS = frozenset({"edit", "patch", "run"})
+SHIP_ACTIONS = frozenset({"issue", "branch", "commit", "push", "pr", "merge"})
+
+
+@dataclass(frozen=True)
+class Ask:
+    """One action the model asked for, and everything it may act on.
+
+    Fields:
+        project: the folder the run may read and write inside.
+        turn: the parsed action, with whichever fields it carried.
+        path: the file this action lands on — the one it named, or the
+            last one touched.
+        last_path: what to report when the action changes no file.
+        scope: the folder to stay inside, if the run was given one.
+        target: the skill target, when a skill is being rendered.
+        task: what the user asked for, in their own words.
+    """
+
+    project: Path
+    turn: object
+    path: str
+    last_path: str
+    scope: str
+    target: object
+    task: str
+
+
+def _locate(ask: Ask) -> tuple[str, str]:
+    return locate_py(ask.project, ask.turn.query or ask.turn.name, ask.scope)
+
+
+def _map(ask: Ask) -> tuple[str, str]:
+    return map_py(ask.project, ask.scope), ask.last_path
+
+
+def _layout(ask: Ask) -> tuple[str, str]:
+    base = resolve_scope(ask.project, ask.scope) if ask.scope else ask.project
+    return render_layout(base), ask.last_path
+
+
+def _plan(ask: Ask) -> tuple[str, str]:
+    return (
+        f"plan noted:\n{ask.turn.summary or '(empty plan)'}\n"
+        "Take the first explore action now."
+    ), ask.last_path
+
+
+def _glob(ask: Ask) -> tuple[str, str]:
+    pattern = ask.turn.pattern or "**/*.py"
+    return glob_py(ask.project, pattern, scope=ask.scope), ask.last_path
+
+
+def _grep(ask: Ask) -> tuple[str, str]:
+    return grep_py(ask.project, ask.turn.query, scope=ask.scope), ask.last_path
+
+
+def _read(ask: Ask) -> tuple[str, str]:
+    if not ask.path:
+        return "read needs Path:", ask.last_path
+    return read_py(ask.project, ask.path), ask.path
+
+
+def _edit(ask: Ask) -> tuple[str, str]:
+    if not ask.path:
+        return "edit needs Path:", ask.last_path
+    if not ask.turn.source:
+        return "edit needs a ```python block", ask.path
+    blocked = PythonVibeGuard().check(ask.turn.source)
+    if blocked.verdict != "pass":
+        return (
+            f"harness blocked: {[f.rule_id for f in blocked.findings]}",
+            ask.path,
+        )
+    return edit_py(ask.project, ask.path, ask.turn.source, task=ask.task), ask.path
+
+
+def _patch(ask: Ask) -> tuple[str, str]:
+    if not ask.path:
+        return "patch needs Path: (or read that file first)", ask.last_path
+    return patch_py(
+        ask.project,
+        ask.path,
+        ask.turn.find,
+        ask.turn.replace,
+        ask.turn.append,
+        task=ask.task,
+    ), ask.path
+
+
+def _run(ask: Ask) -> tuple[str, str]:
+    return run_python(ask.project, ask.turn.argv), ask.last_path
+
+
+def _skill(ask: Ask) -> tuple[str, str]:
+    return (
+        f"skill needs Name:. {render_catalog(list_skills(ask.project))}",
+        ask.last_path,
+    )
+
+
+def _named(ask: Ask) -> str:
+    """The issue or pull request number an action carried."""
+    return (ask.turn.number or ask.turn.name or ask.turn.query or "").strip()
+
+
+def _issue(ask: Ask) -> tuple[str, str]:
+    return read_issue(ask.project, _named(ask)), ask.last_path
+
+
+def _branch(ask: Ask) -> tuple[str, str]:
+    return make_branch(ask.project, ask.turn.name or ask.turn.summary), ask.last_path
+
+
+def _commit(ask: Ask) -> tuple[str, str]:
+    return commit_changes(ask.project, ask.turn.summary), ask.last_path
+
+
+def _push(ask: Ask) -> tuple[str, str]:
+    return push_branch(ask.project), ask.last_path
+
+
+def _pr(ask: Ask) -> tuple[str, str]:
+    """A number reads that pull request; anything else opens one."""
+    number = _named(ask)
+    if number.isdigit():
+        return read_pr(ask.project, number), ask.last_path
+    return create_pr(
+        ask.project,
+        ask.turn.title or ask.turn.summary,
+        ask.turn.body or ask.turn.append,
+    ), ask.last_path
+
+
+def _merge(ask: Ask) -> tuple[str, str]:
+    return merge_pr(ask.project, _named(ask), allowed=True), ask.last_path
+
+
+# One entry per action the model may take. This was nineteen
+# `if turn.action == ...` tests in a row, which hid both the list and
+# the fact that a new action has to be added to it: forgetting meant a
+# silent "unknown Action" rather than an error anyone would notice.
+# `ask` and `done` are answered by the loop before it gets here.
+HANDLERS: dict[str, Callable[[Ask], tuple[str, str]]] = {
+    "locate": _locate,
+    "map": _map,
+    "layout": _layout,
+    "plan": _plan,
+    "glob": _glob,
+    "grep": _grep,
+    "read": _read,
+    "edit": _edit,
+    "patch": _patch,
+    "run": _run,
+    "skill": _skill,
+    "issue": _issue,
+    "branch": _branch,
+    "commit": _commit,
+    "push": _push,
+    "pr": _pr,
+    "merge": _merge,
+}
+
+
+def run_action(
+    project: Path, turn, last_path: str, scope: str, target=None, task: str = ""
+) -> tuple[str, str]:
+    """Carry out one action, and say which file it left the run on."""
+    loaded = skill_from_action(turn.action, turn.name, turn.path, project)
+    if loaded is not None:
+        return render_skill(loaded, target, project), last_path
+    handler = HANDLERS.get(turn.action)
+    if handler is None:
+        return f"unknown Action {turn.action}. Use {ACTIONS}.", last_path
+    return handler(
+        Ask(
+            project=project,
+            turn=turn,
+            path=turn.path or last_path,
+            last_path=last_path,
+            scope=turn.scope or scope,
+            target=target,
+            task=task,
+        )
+    )