harness-agent2 1.1.0__py3-none-any.whl

harness/__init__.py

@@ -0,0 +1,3 @@
+"""Harness - local-first control plane that professionalizes how coding agents work on a repo."""
+
+__version__ = "1.1.0"

harness/__main__.py

@@ -0,0 +1,6 @@
+import sys
+
+from harness.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

harness/agents.py

@@ -0,0 +1,75 @@
+"""Agent adapters: the same contract lifecycle driven by different coding agents.
+
+Enforcement asymmetry, stated honestly: Claude runs under the PreToolUse guard hook
+(.claude/settings.json); Codex has no hook equivalent, so it relies on AGENTS.md rules
+plus its workspace-write sandbox, with the scope gate in `harness verify` catching
+violations after the fact.
+"""
+
+import json
+import shutil
+import subprocess
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from harness.policy import die
+
+
+@dataclass(frozen=True)
+class AgentSpec:
+    binary: str
+    argv: Callable[[str], list[str]]
+    enforcement_tier: str
+    description: str
+
+
+AGENT_SPECS: Mapping[str, AgentSpec] = MappingProxyType({
+    "claude": AgentSpec("claude", lambda prompt: ["claude", "-p", prompt, "--permission-mode", "acceptEdits"],
+                        "guard-hook", "Claude Code with the PreToolUse guard hook."),
+    "codex": AgentSpec("codex", lambda prompt: ["codex", "exec", "--sandbox", "workspace-write", prompt],
+                       "sandbox+verify", "Codex with workspace-write sandbox and verify scope gate."),
+})
+AGENTS = tuple(AGENT_SPECS)
+
+
+def agent_prompt(c) -> str:
+    return (f"Goal: {c['goal']}\nAcceptance criteria:\n" + "\n".join(f"- {x}" for x in c["accept"]) +
+            "\nFirst write a short plan, then implement. Do not touch protected paths. Before finishing, run: " +
+            "; ".join(g["cmd"] for g in c["gates"].values()) + ". Do not claim completion while any fails.")
+
+
+def build_argv(agent: str, prompt: str) -> list[str]:
+    try:
+        return AGENT_SPECS[agent].argv(prompt)
+    except KeyError:
+        die(f"unknown agent: {agent} (supported: {', '.join(AGENT_SPECS)})")
+
+
+def cmd_agents(args) -> int:
+    rows = []
+    for name, spec in AGENT_SPECS.items():
+        path = shutil.which(spec.binary)
+        version = None
+        if path:
+            for flag in ("--version", "version"):
+                try:
+                    result = subprocess.run([path, flag], capture_output=True, text=True, timeout=5, check=False)
+                except (OSError, subprocess.SubprocessError):
+                    continue
+                if result.returncode == 0:
+                    lines = (result.stdout + result.stderr).strip().splitlines()
+                    version = lines[0][:90] if lines else "present"
+                    break
+            if version is None:
+                version = "present"
+        rows.append({"name": name, "binary": spec.binary, "present": path is not None,
+                     "version": version, "enforcement_tier": spec.enforcement_tier})
+    if args.json:
+        print(json.dumps(rows))
+    else:
+        print(f"{'NAME':<12} {'PRESENT':<8} {'VERSION':<24} ENFORCEMENT TIER")
+        for row in rows:
+            print(f"{row['name']:<12} {'yes' if row['present'] else 'no':<8} "
+                  f"{(row['version'] or '-'):<24} {row['enforcement_tier']}")
+    return 0

harness/bundle.py

@@ -0,0 +1,110 @@
+"""Team policy bundle: the shared files of .ai-engineering/ versioned in a Git repo.
+
+Bundle = policy.json + verification.json at .ai-engineering/ in the bundle repo.
+Everything else stays local on purpose: project.json carries machine-specific
+paths, and tasks/evidence/audit.log are per-repo history.
+"""
+
+import shutil
+import subprocess
+import tempfile
+from pathlib import Path
+
+from harness.policy import AE, die, find_root
+
+BUNDLE = ("policy.json", "verification.json")
+
+
+def _git(cwd: Path, *a: str) -> tuple[int, str]:
+    p = subprocess.run(["git", *a], cwd=str(cwd), capture_output=True, text=True, check=False)
+    return p.returncode, (p.stdout + p.stderr).rstrip()
+
+
+def _clone(remote: str, branch: str) -> Path:
+    tmp = Path(tempfile.mkdtemp(prefix="harness-bundle-"))
+    clone = tmp / "repo"
+    rc, out = _git(tmp, "clone", remote, "repo")
+    if rc:
+        shutil.rmtree(tmp, ignore_errors=True)
+        die(f"cannot clone bundle remote {remote!r}: {out}")
+    if _git(clone, "rev-parse", "--verify", f"origin/{branch}")[0] == 0:
+        _git(clone, "checkout", "-B", branch, f"origin/{branch}")
+    else:
+        # non-empty repo without the branch: new branch off HEAD; empty repo: unborn HEAD
+        _git(clone, "checkout", "-B", branch)
+    return clone
+
+
+def _need_local(r: Path) -> None:
+    miss = [n for n in BUNDLE if not (r / AE / n).exists()]
+    if miss:
+        die(f"missing {', '.join(miss)}; run `harness init` first")
+
+
+def _remote_bundle(clone: Path) -> dict[str, str]:
+    out = {}
+    for n in BUNDLE:
+        p = clone / AE / n
+        if p.exists():
+            out[n] = p.read_text()
+        else:
+            die(f"bundle remote has no {AE}/{n}; run `harness policy push` from a member repo first")
+    return out
+
+
+def _push(r: Path, clone: Path, a) -> int:
+    _need_local(r)
+    dst = clone / AE
+    dst.mkdir(parents=True, exist_ok=True)
+    for n in BUNDLE:
+        shutil.copy2(r / AE / n, dst / n)
+    _git(clone, "add", "-A")
+    rc, out = _git(clone, "commit", "-m", f"harness policy bundle: {r.name}")
+    if "nothing to commit" in out:
+        print("Bundle   : unchanged (remote already has this state)")
+        return 0
+    rc, out = _git(clone, "push", "origin", f"HEAD:{a.branch}")
+    if rc:
+        die(f"push failed: {out}")
+    print(f"Pushed   : {_git(clone, 'rev-parse', 'HEAD')[1]} -> {a.remote} ({a.branch})")
+    return 0
+
+
+def _status(r: Path, clone: Path, a) -> int:
+    _need_local(r)
+    remote = _remote_bundle(clone)
+    drift = [n for n in BUNDLE if remote[n] != (r / AE / n).read_text()]
+    for n in drift:
+        print(f"DRIFT    : {AE}/{n} differs from {a.remote} ({a.branch})")
+    if drift:
+        return 1
+    print(f"In sync  : {', '.join(BUNDLE)} match {a.remote} ({a.branch})")
+    return 0
+
+
+def _pull(r: Path, clone: Path, a) -> int:
+    remote = _remote_bundle(clone)
+    updated = []
+    for n in BUNDLE:
+        lp = r / AE / n
+        if not lp.exists() or lp.read_text() != remote[n]:
+            lp.parent.mkdir(parents=True, exist_ok=True)
+            lp.write_text(remote[n])
+            updated.append(n)
+    print(f"Pulled   : {', '.join(updated) if updated else 'nothing (already in sync)'}")
+    return 0
+
+
+def cmd_policy(a) -> int:
+    r = find_root(a.repo)
+    if not r:
+        die("run `harness init` first")
+    clone = _clone(a.remote, a.branch)
+    try:
+        if a.polc == "push":
+            return _push(r, clone, a)
+        if a.polc == "status":
+            return _status(r, clone, a)
+        return _pull(r, clone, a)
+    finally:
+        shutil.rmtree(clone.parent, ignore_errors=True)

harness/ci.py

@@ -0,0 +1,112 @@
+"""CI generator: a GitHub Actions workflow running the readiness floor and the repo's gates.
+
+The YAML is generated from the repo's own verification.json, so CI and
+`harness verify` execute the same commands. Re-running `harness ci` updates the
+file in place (marker line); a hand-written workflow of the same name is only
+touched with --force.
+"""
+
+from pathlib import Path
+
+from harness.policy import AE, die, find_root, jload
+from harness.scan import scan
+
+WORKFLOW = Path(".github") / "workflows" / "harness.yml"
+MARKER = "Generated by `harness ci`"
+LOCKFILES = {"package-lock.json": "npm ci --no-fund --no-audit", "pnpm-lock.yaml": "pnpm install --frozen-lockfile",
+             "yarn.lock": "yarn install --frozen-lockfile"}
+SKIP_DIRS = {"node_modules", ".venv", "venv", "dist", "build", "test-results"}
+
+
+def _manifest_dirs(r: Path) -> list[Path]:
+    """Dirs holding a JS package: the root plus depth-1 app dirs (web/, frontend/…)."""
+    dirs = [r] if (r / "package.json").exists() else []
+    dirs += [p.parent for p in sorted(r.glob("*/package.json")) if p.parent.name not in SKIP_DIRS]
+    return dirs
+
+
+def _install_cmds(r: Path) -> list[str]:
+    cmds = []
+    if (r / "uv.lock").exists():
+        cmds += ["pip install uv", "uv sync --frozen"]  # runners have pip, not uv
+    for f, c in LOCKFILES.items():
+        if (r / f).exists():
+            cmds.append(c)
+    for d in _manifest_dirs(r):
+        if d == r:
+            continue
+        for f, c in LOCKFILES.items():
+            if (d / f).exists():
+                cmds.append(f"cd {d.relative_to(r).as_posix()} && {c}")
+    if not cmds and (r / "pyproject.toml").exists():
+        cmds.append("pip install .")
+    return list(dict.fromkeys(cmds))
+
+
+def _harness_install(r: Path) -> str:
+    """Where CI gets the CLI: this repo when it is harness itself, otherwise a git ref
+    (the package is not on PyPI; secrets.HARNESS_REPO points at the harness repository)."""
+    return "pip install ." if (r / "harness" / "cli.py").exists() else "pip install git+${{ secrets.HARNESS_REPO }}"
+
+
+def _yaml(r: Path, gates: dict, fail_under: int, extra: list[str], install: str) -> str:
+    L = ["# " + MARKER + " — regenerate with `harness ci`; do not edit by hand.",
+         "name: harness",
+         "on:",
+         "  pull_request:",
+         "  push:",
+         "    branches: [main]",
+         "permissions:",
+         "  contents: read",
+         "jobs:",
+         "  readiness:",
+         "    runs-on: ubuntu-latest",
+         "    steps:",
+         "      - uses: actions/checkout@v4",
+         "      - uses: actions/setup-python@v5",
+         "        with:",
+         '          python-version: "3.12"',
+         f'      - run: "{install}"',
+         f'      - run: "harness scan --fail-under {fail_under}"',
+         "  gates:",
+         "    runs-on: ubuntu-latest",
+         "    steps:",
+         "      - uses: actions/checkout@v4"]
+    if _manifest_dirs(r):
+        L += ["      - uses: actions/setup-node@v4",
+              "        with:",
+              '          node-version: "22"']
+    if (r / "pyproject.toml").exists() or (r / "uv.lock").exists() or (r / "requirements.txt").exists():
+        L += ["      - uses: actions/setup-python@v5",
+              "        with:",
+              '          python-version: "3.12"']
+    for c in _install_cmds(r) + extra:
+        L += [f'      - run: "{c}"']
+    for name, g in gates.items():
+        L += [f"      - name: gate {name}", f'        run: "{g["cmd"]}"']
+    if not gates:
+        L += ["      - name: no gates detected", "        run: \"echo 'run harness init to add gates'\""]
+    return "\n".join(L) + "\n"
+
+
+def cmd_ci(a) -> int:
+    r = find_root(a.repo)
+    if not r:
+        die("run `harness init` first")
+    v = jload(r / AE / "verification.json")
+    floor = a.fail_under
+    if floor is None:
+        measured = scan(r)["readiness"]
+        floor = min(70, measured)
+        if measured < 70:
+            print(f"Note   : repo readiness is {measured}/100 — clamped floor to {floor}; "
+                  "pass --fail-under explicitly to override")
+    dst = r / WORKFLOW
+    if dst.exists() and MARKER not in dst.read_text() and not a.force:
+        die(f"{WORKFLOW} is hand-written; keep it or re-run with --force")
+    dst.parent.mkdir(parents=True, exist_ok=True)
+    dst.write_text(_yaml(r, v.get("gates", {}), floor, a.setup or [],
+                         a.install or _harness_install(r)))
+    print(f"Wrote    : {WORKFLOW} ({len(v.get('gates', {}))} gates, floor {floor}) — commit it; "
+          "GitHub Actions runs it on push/PR")
+    return 0

harness/cli.py

@@ -0,0 +1,134 @@
+"""Argparse surface. Exit codes: 0 ok, 1 policy/contract failure or die(), 2 reserved for guard block."""
+
+import argparse
+import sys
+
+from harness import __version__
+from harness.agents import AGENTS, cmd_agents
+from harness.bundle import cmd_policy
+from harness.ci import cmd_ci
+from harness.contract import cmd_list, cmd_run, cmd_start, cmd_update
+from harness.eval import VARIANTS, cmd_eval
+from harness.guard import cmd_guard
+from harness.policy import LVL, cmd_init
+from harness.pr import cmd_pr
+from harness.scan import cmd_scan
+from harness.verify import cmd_verify
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="harness",
+                                description="Local-first control plane that professionalizes how "
+                                            "coding agents work on a repo: scan -> init -> task start "
+                                            "-> (task run) -> verify -> pr.")
+    p.add_argument("--version", action="version", version=f"harness {__version__}")
+    p.add_argument("--repo", default=".")
+    s = p.add_subparsers(dest="c", required=True)
+
+    x = s.add_parser("scan", help="detect stacks, gates, protected paths; score agent-readiness")
+    x.add_argument("--json", action="store_true")
+    x.add_argument("--fail-under", type=int, metavar="N", help="exit 1 when readiness scores below N (CI gate)")
+    x.set_defaults(f=cmd_scan)
+
+    x = s.add_parser("init", help="write .ai-engineering/, CLAUDE.md, AGENTS.md and .claude/settings.json")
+    x.add_argument("--force", action="store_true")
+    x.set_defaults(f=cmd_init)
+
+    s.add_parser("guard", help=argparse.SUPPRESS).set_defaults(f=cmd_guard)
+
+    x = s.add_parser("agents", help="show supported agent binaries and enforcement tiers")
+    x.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    x.set_defaults(f=cmd_agents)
+
+    t = s.add_parser("task", help="manage contracts").add_subparsers(dest="t", required=True)
+    x = t.add_parser("start")
+    x.add_argument("name")
+    x.add_argument("--goal", required=True)
+    x.add_argument("--accept", action="append")
+    x.add_argument("--allow", action="append")
+    x.add_argument("--risk", choices=list(LVL), default="medium")
+    x.set_defaults(f=cmd_start)
+    x = t.add_parser("run", help="optional headless agent run inside the worktree")
+    x.add_argument("name")
+    x.add_argument("--agent", choices=list(AGENTS), default="claude")
+    x.set_defaults(f=cmd_run)
+    x = t.add_parser("update", help="amend a contract (goal/accept/allow/risk)")
+    x.add_argument("name")
+    x.add_argument("--goal")
+    x.add_argument("--accept", action="append")
+    x.add_argument("--allow", action="append")
+    x.add_argument("--risk", choices=list(LVL))
+    x.set_defaults(f=cmd_update)
+    x = t.add_parser("list")
+    x.set_defaults(f=cmd_list)
+
+    x = s.add_parser("verify", help="run gates + scope + review, emit evidence")
+    x.add_argument("name")
+    x.set_defaults(f=cmd_verify)
+
+    x = s.add_parser("pr", help="gh-backed PR operations for task branches")
+    prs = x.add_subparsers(dest="prc", required=True)
+    y = prs.add_parser("create", help="commit, push, gh pr create (requires PASS evidence)")
+    y.add_argument("name")
+    y = prs.add_parser("view", help="show the PR opened for the task branch")
+    y.add_argument("name")
+    prs.add_parser("status", help="gh pr status")
+    prs.add_parser("list", help="gh pr list")
+    x.set_defaults(f=cmd_pr)
+
+    x = s.add_parser("policy", help="sync the team policy bundle (policy.json + verification.json) with a Git repo")
+    ps = x.add_subparsers(dest="polc", required=True)
+    for nm, hp in (("push", "publish local policy + gates to the bundle repo"),
+                   ("pull", "adopt the bundle as the local team standard"),
+                   ("status", "exit 1 when the local bundle differs from the remote")):
+        y = ps.add_parser(nm, help=hp)
+        y.add_argument("remote", help="bundle repo path or URL")
+        y.add_argument("--branch", default="main")
+    x.set_defaults(f=cmd_policy)
+
+    x = s.add_parser("ci", help="generate .github/workflows/harness.yml (readiness floor + gates)")
+    x.add_argument("--fail-under", type=int, metavar="N",
+                   help="readiness floor in the workflow (default: min(70, the repo's measured score))")
+    x.add_argument("--setup", action="append", metavar="CMD",
+                   help="extra step the gates need before they can run (repeatable), e.g. "
+                        '"cd web && npx playwright install --with-deps chromium"')
+    x.add_argument("--install", metavar="CMD",
+                   help="how CI installs the harness CLI (default: this repo when it is harness, "
+                        "otherwise `pip install harness-agent`)")
+    x.add_argument("--force", action="store_true", help="overwrite a hand-written workflow")
+    x.set_defaults(f=cmd_ci)
+
+    x = s.add_parser("eval", help="P7: run the raw-vs-harnessed corpus and report metrics")
+    evs = x.add_subparsers(dest="ev", required=True)
+    evs.add_parser("list", help="show the task matrix").set_defaults(f=cmd_eval)
+    y = evs.add_parser("run", help="run evals (fake agent with --dry; provider calls otherwise)")
+    y.add_argument("--task", help="only this task id")
+    y.add_argument("--agent", choices=[*AGENTS, "all"], default="all")
+    y.add_argument("--variant", choices=[*VARIANTS, "all"], default="all")
+    y.add_argument("--dry", action="store_true", help="no provider calls: fake no-op agent, plumbing proof")
+    y.add_argument("--keep", action="store_true", help="keep throwaway workdirs for post-mortem")
+    y.set_defaults(f=cmd_eval)
+    evs.add_parser("report", help="render evals/report.html from evals/results.jsonl").set_defaults(f=cmd_eval)
+
+
+    x = s.add_parser("serve", help="local API server for the dashboard (needs server extra)")
+    x.add_argument("--host", default="127.0.0.1")
+    x.add_argument("--port", type=int, default=8766)
+    x.add_argument("--max-parallel", type=int, default=2, help="concurrent agent/verify runs (plan §4.3)")
+    x.set_defaults(f=_serve)
+
+    a = p.parse_args(argv)
+    return a.f(a) or 0
+
+
+def _serve(a) -> int:
+    try:
+        from harness.server import cmd_serve
+    except ImportError:
+        from harness.policy import die
+        die("fastapi/uvicorn missing; run `uv sync --extra server` or `uv tool install harness-agent --with fastapi --with uvicorn`")
+    return cmd_serve(a)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

harness/contract.py

@@ -0,0 +1,100 @@
+"""Task contracts: start/update/list and the optional headless agent run."""
+
+import shutil
+import time
+from pathlib import Path
+
+from harness.policy import AE, LVL, die, find_root, jload, jsave
+from harness.shellx import git, sh
+
+
+def tdir(r: Path) -> Path:
+    return r / AE / "tasks"
+
+
+def load_task(a) -> tuple:
+    r = find_root(a.repo)
+    if not r:
+        die("run `harness init` first")
+    p = tdir(r) / f"{a.name}.json"
+    if not p.exists():
+        die(f"no such task: {a.name}")
+    return r, jload(p)
+
+
+def cmd_start(a) -> int:
+    r = find_root(a.repo)
+    if not r:
+        die("run `harness init` first")
+    wt = r.parent / ".harness-worktrees" / f"{r.name}-{a.name}"
+    br = f"harness/{a.name}"
+    base = git(r, "rev-parse", "HEAD")[1]
+    rc, out, _ = git(r, "worktree", "add", "-b", br, str(wt))
+    if rc:
+        die(out)
+    for p in (AE, ".claude", "CLAUDE.md", "AGENTS.md"):
+        s, d = r / p, wt / p
+        if s.exists() and not d.exists():
+            if s.is_dir():
+                shutil.copytree(s, d, ignore=shutil.ignore_patterns("tasks", "evidence", "audit.log"))
+            else:
+                shutil.copy2(s, d)
+    v = jload(r / AE / "verification.json")
+    pol = jload(r / AE / "policy.json")
+    gates = {k: g for k, g in v["gates"].items() if LVL[g["min_risk"]] <= LVL[a.risk]}
+    con = {"name": a.name, "goal": a.goal, "accept": a.accept or [], "risk": a.risk, "branch": br,
+           "worktree": str(wt), "base": base, "allowed": a.allow or ["**"], "protected": pol["protected"],
+           "gates": gates, "review": v.get("review", True) and a.risk != "low", "created": int(time.time())}
+    jsave(tdir(r) / f"{a.name}.json", con)
+    print(f"Worktree : {wt}\nBranch   : {br}\nGates    : {', '.join(gates) or 'none (!)'}")
+    print(f"Next     : harness task run {a.name}   |   harness verify {a.name}")
+    return 0
+
+
+def cmd_update(a) -> int:
+    r, c = load_task(a)
+    if a.goal:
+        c["goal"] = a.goal
+    if a.accept:
+        c["accept"] = a.accept
+    if a.allow:
+        c["allowed"] = a.allow
+    if a.risk and a.risk != c["risk"]:
+        c["risk"] = a.risk
+        v = jload(r / AE / "verification.json")
+        c["gates"] = {k: g for k, g in v["gates"].items() if LVL[g["min_risk"]] <= LVL[a.risk]}
+        c["review"] = v.get("review", True) and c["risk"] != "low"
+    jsave(tdir(r) / f"{c['name']}.json", c)
+    print(f"Updated  : {c['name']}\nRisk     : {c['risk']}\nGates    : {', '.join(c['gates']) or 'none (!)'}")
+    print(f"Allowed  : {', '.join(c['allowed'])}")
+    return 0
+
+
+def cmd_list(a) -> int:
+    r = find_root(a.repo)
+    if not r:
+        die("run `harness init` first")
+    d = tdir(r)
+    rows = []
+    for p in sorted(d.glob("*.json")) if d.is_dir() else []:
+        c = jload(p)
+        ep = r / AE / "evidence" / f"{c['name']}.json"
+        verdict = jload(ep)["verdict"] if ep.exists() else "unverified"
+        rows.append(f"{c['name']:<20} {c['risk']:<7} {c['branch']:<28} {verdict}")
+    if not rows:
+        print("no tasks")
+    for row in rows:
+        print(row)
+    return 0
+
+
+def cmd_run(a) -> int:
+    from harness.agents import agent_prompt, build_argv
+
+    _, c = load_task(a)
+    if not shutil.which(a.agent):
+        die(f"`{a.agent}` CLI not found; work in the worktree manually, then `harness verify`.")
+    rc, out, _ = sh(build_argv(a.agent, agent_prompt(c)), c["worktree"], timeout=3600)
+    if out:
+        print(out)
+    return rc