agentflow-proof 1.0.0__py3-none-any.whl

agentflow/git.py

@@ -0,0 +1,89 @@
+"""Git helpers used by drift auditing."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+
+def run_git(root: Path, args: List[str]) -> Tuple[int, str, str]:
+    proc = subprocess.run(
+        ["git", "-C", str(root), *args],
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    return proc.returncode, proc.stdout.rstrip(), proc.stderr.rstrip()
+
+
+def is_git_repo(root: Path) -> bool:
+    code, _, _ = run_git(root, ["rev-parse", "--is-inside-work-tree"])
+    return code == 0
+
+
+def changed_files(root: Path) -> List[str]:
+    code, stdout, stderr = run_git(root, ["status", "--porcelain=v1", "-uall"])
+    if code != 0:
+        raise RuntimeError(stderr or "git status failed")
+
+    files = []
+    for line in stdout.splitlines():
+        if not line:
+            continue
+        path = line[3:].strip()
+        if " -> " in path:
+            path = path.split(" -> ", 1)[1]
+        files.append(path)
+    return sorted(set(files))
+
+
+def changed_file_records(root: Path) -> List[Dict[str, str]]:
+    code, stdout, stderr = run_git(root, ["status", "--porcelain=v1", "-uall"])
+    if code != 0:
+        raise RuntimeError(stderr or "git status failed")
+
+    records: List[Dict[str, str]] = []
+    for line in stdout.splitlines():
+        if not line:
+            continue
+        status = line[:2]
+        raw_path = line[3:].strip()
+        previous_path = ""
+        path = raw_path
+        change_kind = "modified"
+        if " -> " in raw_path:
+            previous_path, path = raw_path.split(" -> ", 1)
+            change_kind = "renamed"
+        elif status == "??" or "A" in status:
+            change_kind = "added"
+        elif "D" in status:
+            change_kind = "deleted"
+        records.append(
+            {
+                "path": path,
+                "previous_path": previous_path,
+                "status": status,
+                "change_kind": change_kind,
+            }
+        )
+    return sorted(records, key=lambda item: item["path"])
+
+
+def git_blob_for_head(root: Path, path: str) -> Optional[str]:
+    code, stdout, _ = run_git(root, ["rev-parse", f"HEAD:{path}"])
+    if code != 0:
+        return None
+    return stdout.strip()
+
+
+def current_branch(root: Path) -> Optional[str]:
+    """Return the current branch name, or None outside a repo / on detached HEAD."""
+    code, stdout, _ = run_git(root, ["rev-parse", "--abbrev-ref", "HEAD"])
+    if code != 0:
+        return None
+    branch = stdout.strip()
+    if not branch or branch == "HEAD":
+        return None
+    return branch

agentflow/handoff.py

@@ -0,0 +1,112 @@
+"""Provider-neutral handoff rendering."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Union
+
+from .contracts import PROVIDER_NEUTRAL_DENYLIST
+
+
+def _step(plan: Dict[str, Any], step_id: str) -> Dict[str, Any]:
+    for item in plan.get("steps", []):
+        if isinstance(item, dict) and item.get("id") == step_id:
+            return item
+    raise ValueError(f"unknown step id: {step_id}")
+
+
+def lint_handoff_text(text: str) -> List[Dict[str, str]]:
+    lower = text.lower()
+    findings: List[Dict[str, str]] = []
+    for token in PROVIDER_NEUTRAL_DENYLIST:
+        if token in lower:
+            findings.append(
+                {
+                    "severity": "error",
+                    "message": f"provider-specific token is not allowed in handoff: {token}",
+                }
+            )
+    return findings
+
+
+def _json_handoff(plan: Dict[str, Any], step_id: str) -> Dict[str, Any]:
+    step = _step(plan, step_id)
+    return {
+        "contract": "agentflow_shell_handoff",
+        "objective": plan.get("objective", ""),
+        "step": step,
+        "allowed_files": step.get("files", []),
+        "blocked_files": plan.get("blocked_files", []),
+        "non_goals": plan.get("non_goals", []),
+        "invariants": plan.get("invariants", []),
+        "expected_diff": step.get("expected_diff", []),
+        "validation": step.get("validation", []),
+        "commands": {
+            "claim": f"agentflow claim-step {step_id} --agent $AGENT_ID",
+            "run": f"agentflow run --step {step_id} -- <command>",
+            "record_file_change": f"agentflow record-file-change --step {step_id} --path <path>",
+            "verify": f"agentflow verify-step {step_id}",
+            "complete": f"agentflow complete-step {step_id}",
+            "block": f"agentflow block-step {step_id} --reason <reason>",
+            "fail": f"agentflow fail-step {step_id} --reason <reason>",
+        },
+        "exit_code_contract": {
+            "0": "no error-severity findings",
+            "1": "one or more error-severity findings",
+            "2": "command usage error",
+        },
+    }
+
+
+def _markdown_handoff(payload: Dict[str, Any]) -> str:
+    step = payload["step"]
+    lines = [
+        "# Agentflow Work Packet",
+        "",
+        "## Objective",
+        "",
+        payload["objective"],
+        "",
+        "## Step",
+        "",
+        f"{step['id']}: {step['action']}",
+        "",
+        "## Allowed Files",
+        "",
+        *[f"- {item}" for item in payload["allowed_files"]],
+        "",
+        "## Blocked Files",
+        "",
+        *[f"- {item}" for item in payload["blocked_files"]],
+        "",
+        "## Expected Diff",
+        "",
+        *[f"- {item}" for item in payload["expected_diff"]],
+        "",
+        "## Validation",
+        "",
+        *[f"- {item}" for item in payload["validation"]],
+        "",
+        "## Commands",
+        "",
+        *[f"- `{name}`: `{command}`" for name, command in payload["commands"].items()],
+        "",
+    ]
+    return "\n".join(lines)
+
+
+def export_handoff(plan: Dict[str, Any], step_id: str, output_format: str) -> Union[Dict[str, Any], str]:
+    payload = _json_handoff(plan, step_id)
+    if output_format == "json":
+        text = json.dumps(payload, sort_keys=True)
+        findings = lint_handoff_text(text)
+        if findings:
+            raise ValueError(findings[0]["message"])
+        return payload
+    if output_format == "markdown":
+        markdown = _markdown_handoff(payload)
+        findings = lint_handoff_text(markdown)
+        if findings:
+            raise ValueError(findings[0]["message"])
+        return markdown
+    raise ValueError("format must be json or markdown")

agentflow/hunks.py

@@ -0,0 +1,245 @@
+"""Hunk-level attribution: shared diff parsing, identity, and coverage.
+
+This module is the only place that shells ``git diff`` and computes hunk
+identity hashes. It imports only stdlib plus ``artifacts`` and ``contracts`` to
+stay free of import cycles (``receipts``/``validation``/``execution_coverage``
+all import this module). It deliberately does not use ``git.run_git`` because
+that helper strips stdout, and hunk patches / HEAD blobs need exact output.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import subprocess
+from pathlib import Path
+from tempfile import NamedTemporaryFile
+from typing import Any, Dict, List, Optional, Tuple
+
+from .artifacts import read_jsonl, try_read_json
+from .contracts import DIFF_COMMAND_VERSION, EXECUTION_ARTIFACT_PATHS, HUNK_ATTRIBUTION_POLICIES
+
+_HUNK_HEADER = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+# Number of lines before each hunk to include in the context anchor window.
+_CONTEXT_ANCHOR_LINES = 3
+
+
+def _git_text(root: Path, args: List[str]) -> Tuple[int, str, str]:
+    proc = subprocess.run(
+        ["git", "-C", str(root), *args],
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        encoding="utf-8",
+        errors="surrogateescape",
+    )
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+def _git_bytes(root: Path, args: List[str]) -> Tuple[int, bytes, bytes]:
+    proc = subprocess.run(
+        ["git", "-C", str(root), *args],
+        check=False,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    return proc.returncode, proc.stdout, proc.stderr
+
+
+def _base_flags(no_index: bool) -> List[str]:
+    flags = [
+        "-c",
+        "core.autocrlf=false",
+        "diff",
+        "--no-color",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--unified=0",
+        "--diff-algorithm=myers",
+    ]
+    flags.append("--no-index" if no_index else "--no-renames")
+    return flags
+
+
+def hunk_identity(posix_path: str, change_kind: str, changed_lines: List[str]) -> str:
+    payload = "\n".join([DIFF_COMMAND_VERSION, posix_path, change_kind, *changed_lines])
+    return hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+def _normalize_path(path: str) -> str:
+    return path.replace("\\", "/")
+
+
+def _head_lines(root: Path, path: str) -> Optional[List[str]]:
+    code, stdout, _ = _git_text(root, ["show", f"HEAD:{path}"])
+    if code != 0:
+        return None
+    # CRLF→LF normalization is deliberate: ensures cross-platform identity stability.
+    return stdout.replace("\r\n", "\n").split("\n")
+
+
+def _context_sha256(head_lines: Optional[List[str]], old_start: int) -> Tuple[Optional[str], str]:
+    if not head_lines or old_start <= 0:
+        return None, "none"
+    start = max(0, old_start - 1 - _CONTEXT_ANCHOR_LINES)
+    anchors = head_lines[start : old_start - 1]
+    if not anchors:
+        return None, "none"
+    digest = hashlib.sha256("\n".join(anchors).encode("utf-8")).hexdigest()
+    return digest, "head-baseline"
+
+
+def _parse_patch(text: str, posix_path: str, change_kind: str, head_lines: Optional[List[str]]) -> List[Dict[str, Any]]:
+    hunks: List[Dict[str, Any]] = []
+    # CRLF→LF normalization is deliberate: ensures cross-platform identity stability.
+    lines = text.replace("\r\n", "\n").split("\n")
+    index = 0
+    while index < len(lines):
+        match = _HUNK_HEADER.match(lines[index])
+        if not match:
+            index += 1
+            continue
+        old_start = int(match.group(1))
+        old_count = int(match.group(2) or "1")
+        new_start = int(match.group(3))
+        new_count = int(match.group(4) or "1")
+        index += 1
+        body: List[str] = []
+        # Safe under --unified=0: no context lines are emitted, so every
+        # added/removed content line carries a '+'/'-' prefix; a literal "@@ "
+        # sequence in file content cannot appear without a prefix and cannot be
+        # misread as a hunk header.
+        while index < len(lines) and not lines[index].startswith("@@ "):
+            line = lines[index]
+            if line.startswith(("+", "-")):
+                body.append(line)
+            index += 1
+        context_hash, context_source = _context_sha256(head_lines, old_start)
+        hunks.append(
+            {
+                "hash": hunk_identity(posix_path, change_kind, body),
+                "old_start": old_start,
+                "old_count": old_count,
+                "new_start": new_start,
+                "new_count": new_count,
+                "context_sha256": context_hash,
+                "context_source": context_source,
+            }
+        )
+    return hunks
+
+
+def _is_binary(text: str) -> bool:
+    return "Binary files " in text or "GIT binary patch" in text
+
+
+def compute_hunks(root: Path, record: Dict[str, Any]) -> Tuple[str, List[Dict[str, Any]]]:
+    """Return ``(attribution, hunks)`` for one changed-file record.
+
+    ``attribution`` is ``"hunked"`` for a parsed text diff or
+    ``"whole_file_fallback"`` for binary / unparseable / unreconstructable
+    inputs. The ``"disabled"`` state is set by the caller, never here.
+    """
+    path = record["path"]
+    posix_path = _normalize_path(path)
+    change_kind = record.get("change_kind", "modified")
+    head_lines = _head_lines(root, record.get("previous_path") or path)
+
+    if change_kind == "added":
+        code, stdout, _ = _git_text(root, [*_base_flags(no_index=True), "--", "/dev/null", path])
+        if code > 1:
+            return "whole_file_fallback", []
+        if _is_binary(stdout):
+            return "whole_file_fallback", []
+        return "hunked", _parse_patch(stdout, posix_path, change_kind, None)
+
+    if change_kind == "renamed":
+        previous_path = record.get("previous_path") or ""
+        if not previous_path:
+            return "whole_file_fallback", []
+        code, blob, _ = _git_bytes(root, ["show", f"HEAD:{previous_path}"])
+        if code != 0:
+            return "whole_file_fallback", []
+        with NamedTemporaryFile("wb", suffix=".afhunk", delete=True) as handle:
+            handle.write(blob)
+            handle.flush()
+            code, stdout, _ = _git_text(
+                root, [*_base_flags(no_index=True), "--", handle.name, path]
+            )
+        if code > 1 or _is_binary(stdout):
+            return "whole_file_fallback", []
+        return "hunked", _parse_patch(stdout, posix_path, change_kind, head_lines)
+
+    # modified / deleted: working tree vs HEAD
+    code, stdout, _ = _git_text(root, [*_base_flags(no_index=False), "HEAD", "--", path])
+    if code != 0:
+        return "whole_file_fallback", []
+    if _is_binary(stdout):
+        return "whole_file_fallback", []
+    return "hunked", _parse_patch(stdout, posix_path, change_kind, head_lines)
+
+
+def effective_hunk_policy(root: Path) -> str:
+    contract_path = root / EXECUTION_ARTIFACT_PATHS["execution-contract"]
+    if not contract_path.exists():
+        return "off"
+    # A malformed contract must not crash the proof/CI gate; degrade to the
+    # contract-present default ("enforce") rather than raising.
+    contract, _ = try_read_json(contract_path)
+    if not isinstance(contract, dict):
+        return "enforce"
+    policy = contract.get("proof_policy", {})
+    value = policy.get("hunk_attribution", "enforce") if isinstance(policy, dict) else "enforce"
+    return value if value in HUNK_ATTRIBUTION_POLICIES else "enforce"
+
+
+def _receipts_by_path(root: Path) -> Tuple[Dict[str, Dict[str, Any]], Dict[str, List[Dict[str, Any]]]]:
+    latest: Dict[str, Dict[str, Any]] = {}
+    grouped: Dict[str, List[Dict[str, Any]]] = {}
+    for receipt in read_jsonl(root / EXECUTION_ARTIFACT_PATHS["file-receipts"]):
+        path = receipt.get("path")
+        if not isinstance(path, str):
+            continue
+        latest[path] = receipt  # append-only ledger: last write wins
+        grouped.setdefault(path, []).append(receipt)
+    return latest, grouped
+
+
+def unmapped_hunks(root: Path, records: List[Dict[str, Any]]) -> List[Dict[str, Any]]:
+    latest, grouped = _receipts_by_path(root)
+    out: List[Dict[str, Any]] = []
+    for record in records:
+        path = record.get("path")
+        latest_receipt = latest.get(path)
+        if latest_receipt is None:
+            continue  # missing-receipt policy handles this upstream
+        path_receipts = grouped.get(path, [])
+        if "hunks" not in latest_receipt:
+            continue  # latest legacy 0.3.0 receipt -> whole-file coverage
+        if latest_receipt.get("hunk_attribution") != "hunked":
+            continue  # whole_file_fallback / disabled
+        recorded = {
+            hunk["hash"]
+            for receipt in path_receipts
+            if receipt.get("hunk_attribution") == "hunked"
+            for hunk in receipt.get("hunks", [])
+            if isinstance(hunk.get("hash"), str)
+        }
+        attribution, current = compute_hunks(root, record)
+        if attribution != "hunked":
+            continue  # became binary/unparseable -> after_sha256 governs
+        for hunk in current:
+            if hunk["hash"] not in recorded:
+                out.append(
+                    {
+                        "path": path,
+                        "hash": hunk["hash"],
+                        "old_start": hunk["old_start"],
+                        "old_count": hunk["old_count"],
+                        "new_start": hunk["new_start"],
+                        "new_count": hunk["new_count"],
+                        "reason": "no_matching_hunk",
+                    }
+                )
+    return out

agentflow/locks.py

@@ -0,0 +1,71 @@
+"""Cross-platform advisory file locking for serializing ledger writes.
+
+Standard library only, to preserve Agentflow's no-runtime-dependency invariant.
+Uses ``fcntl`` on POSIX and ``msvcrt`` on Windows. If neither is available (no
+known platform), the lock degrades to a no-op, which preserves prior behavior.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import time
+from pathlib import Path
+from typing import Iterator
+
+# Poll interval for the Windows retry loop (POSIX flock blocks in the kernel and
+# needs no polling).
+_MSVCRT_RETRY_SECONDS = 0.05
+
+try:  # POSIX
+    import fcntl
+
+    _HAVE_FCNTL = True
+except ImportError:  # pragma: no cover - non-POSIX
+    _HAVE_FCNTL = False
+
+try:  # Windows
+    import msvcrt
+
+    _HAVE_MSVCRT = True
+except ImportError:  # pragma: no cover - non-Windows
+    _HAVE_MSVCRT = False
+
+
+@contextlib.contextmanager
+def file_lock(lock_path: Path) -> Iterator[None]:
+    """Hold an exclusive advisory lock on ``lock_path`` for the block's duration.
+
+    The lock file is created if needed and never truncated; only its kernel lock
+    state is used. The lock is released and the descriptor closed on exit, even if
+    the body raises. ``fcntl`` locks are released by the kernel if the process
+    dies, so a crash cannot leave a stale lock behind.
+    """
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    handle = open(lock_path, "a+")
+    acquired = False
+    try:
+        if _HAVE_FCNTL:
+            fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
+            acquired = True
+        elif _HAVE_MSVCRT:  # pragma: no cover - Windows only
+            # LK_LOCK gives up with OSError after ~10 retries, so a long-held
+            # lock would make concurrent writers fail. Poll a non-blocking lock
+            # until acquired to match POSIX flock's indefinite blocking.
+            handle.seek(0)
+            while True:
+                try:
+                    msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
+                    acquired = True
+                    break
+                except OSError:
+                    time.sleep(_MSVCRT_RETRY_SECONDS)
+        yield
+    finally:
+        try:
+            if acquired and _HAVE_FCNTL:
+                fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
+            elif acquired and _HAVE_MSVCRT:  # pragma: no cover - Windows only
+                handle.seek(0)
+                msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
+        finally:
+            handle.close()