align-agent 0.4.3__py3-none-any.whl

align_agent/writethrough/_lib/wt_src/harness/tail_diff.py

@@ -0,0 +1,292 @@
+"""The tail-diff coherence mechanism, decoupled from any one agent scaffold.
+
+Unlike full-file JIT Tail Refresh (Arm 7), which dumps the entire file (2k-4.2k
+lines, $O(N)$ tokens) and rewrites earlier turns in the history (annihilating
+the KV-cache prefix), this mechanism:
+1. Is strictly append-only: past conversation turns are never modified,
+   preserving 100% of the prefix KV-cache in local engines (vLLM, SGLang) and APIs.
+2. Computes the net unified diff or line-numbered diff hunk between what the
+   agent last saw (held view) and the current live file on disk ($O(\\Delta)$ tokens).
+3. Naturally captures multiple disjoint hunks across large files (solving the
+   single-window limitation of Arm 9 Write-Through Viewport, which misses edits
+   outside a +/- 25 line window).
+4. Handles sequential conflicting overwrites by collapsing intermediate mutations
+   into the exact net diff from the agent's held view to live disk.
+"""
+
+import copy
+import difflib
+import os
+from typing import Any, Dict, List, Optional, Protocol, Tuple
+
+TAIL_DIFF_CONTEXT = 3
+TAIL_DIFF_MAX_FILES = 3
+TAIL_DIFF_MAX_LINE = 200
+TAIL_DIFF_MAX_CHARS = 10_000
+
+
+class _BindingsSource(Protocol):
+    bindings: List[object]  # each binding needs .file_path and .file_content
+
+
+def _is_binary(path: str) -> bool:
+    try:
+        with open(path, "rb") as f:
+            return b"\0" in f.read(8192)
+    except OSError:
+        return True
+
+
+def _clip(line: str) -> str:
+    body = line.rstrip("\n")
+    if len(body) <= TAIL_DIFF_MAX_LINE:
+        return line
+    tail = "\n" if line.endswith("\n") else ""
+    return f"{body[:TAIL_DIFF_MAX_LINE]} ...[{len(body) - TAIL_DIFF_MAX_LINE} more characters]{tail}"
+
+
+def format_line_numbered_diff(
+    held_content: str,
+    disk_content: str,
+    filename: str,
+    context: int = TAIL_DIFF_CONTEXT,
+    step_seen: Optional[int] = None,
+    current_step: Optional[int] = None,
+) -> str:
+    """Format a diff between held content and live disk with explicit live line numbers."""
+    held_lines = held_content.splitlines()
+    disk_lines = disk_content.splitlines()
+    matcher = difflib.SequenceMatcher(None, held_lines, disk_lines)
+
+    step_info = f" (held at Step {step_seen})" if step_seen is not None else ""
+    curr_info = f" (Step {current_step})" if current_step is not None else ""
+    
+    blocks: List[str] = []
+    for tag, alo, ahi, blo, bhi in matcher.get_opcodes():
+        if tag == "equal":
+            continue
+
+        c_alo = max(0, alo - context)
+        c_ahi = min(len(held_lines), ahi + context)
+        c_blo = max(0, blo - context)
+        c_bhi = min(len(disk_lines), bhi + context)
+
+        hunk_header = (
+            f"@@ Held Lines {c_alo + 1}-{c_ahi}{step_info} "
+            f"-> Live Disk Lines {c_blo + 1}-{c_bhi}{curr_info} @@"
+        )
+        lines_out = [hunk_header]
+
+        # Context lines before change (using current live disk line numbers)
+        for lno in range(c_blo, blo):
+            lines_out.append(f"{lno + 1:4d}   {_clip(disk_lines[lno])}")
+
+        # Removed lines from held view
+        for lno in range(alo, ahi):
+            lines_out.append(f"     - {_clip(held_lines[lno])}")
+
+        # Added / modified lines on disk with current line numbers
+        for lno in range(blo, bhi):
+            lines_out.append(f"{lno + 1:4d} + {_clip(disk_lines[lno])}")
+
+        # Context lines after change
+        for lno in range(bhi, c_bhi):
+            lines_out.append(f"{lno + 1:4d}   {_clip(disk_lines[lno])}")
+
+        blocks.append("\n".join(lines_out))
+
+    if not blocks:
+        return ""
+
+    return (
+        f"[TAIL DIFF: File '{filename}' mutated on disk vs your held view]:\n"
+        + "\n\n".join(blocks)
+    )
+
+
+def tail_diff_blocks(
+    workspace_dir: str,
+    files: List[str],
+    freshness_hook: Optional[_BindingsSource] = None,
+    before_contents: Optional[Dict[str, str]] = None,
+    context_lines: int = TAIL_DIFF_CONTEXT,
+    line_numbered: bool = True,
+    current_step: Optional[int] = None,
+) -> Tuple[str, List[str]]:
+    """Compute tail-diff blocks for the specified files against held views.
+
+    The held view is the latest binding from a step before `current_step`: a
+    read in the step that wrote the file was registered with the file as it
+    stood after the write, and diffing against it would show nothing. With no
+    earlier view, the content before this step is the baseline.
+
+    Returns the formatted diff text and the list of files successfully shown.
+    """
+    if not files:
+        return "", []
+
+    bindings = getattr(freshness_hook, "bindings", None) or []
+    from .viewport import _ignored  # generated output is not file state (harness v12)
+    ignored = _ignored(workspace_dir, list(files))
+    files = [f for f in files if f not in ignored]
+    known = set(before_contents or ()) | {getattr(b, "file_path", None) for b in bindings}
+    blocks: List[str] = []
+    shown: List[str] = []
+    used_chars = 0
+
+    for rel_path in sorted(files, key=lambda p: (p not in known, p)):
+        abs_path = os.path.join(workspace_dir, rel_path) if not os.path.isabs(rel_path) else rel_path
+        if not os.path.isfile(abs_path) or _is_binary(abs_path):
+            continue
+        if len(shown) >= TAIL_DIFF_MAX_FILES:
+            break
+
+        try:
+            with open(abs_path, "r", encoding="utf-8", errors="replace") as f:
+                disk_content = f.read()
+        except OSError:
+            continue
+
+        # Locate held content and step ID
+        held_content = None
+        step_seen = None
+        for b in reversed(bindings):
+            if getattr(b, "file_path", None) != rel_path:
+                continue
+            if current_step is not None and getattr(b, "step_id", None) is not None and b.step_id >= current_step:
+                continue  # this step's own read: the file after the write
+            held_content = getattr(b, "file_content", None) or getattr(b, "raw_content", None)
+            step_seen = getattr(b, "step_id", None)
+            break
+
+        if held_content is None and before_contents and rel_path in before_contents:
+            held_content = before_contents[rel_path]
+
+        if held_content is None:
+            # No prior view exists: agent never read this file
+            continue
+
+        if held_content == disk_content:
+            # File matches held view: no staleness
+            continue
+
+        if line_numbered:
+            diff_text = format_line_numbered_diff(
+                held_content, disk_content, rel_path, context=context_lines, step_seen=step_seen
+            )
+        else:
+            diff_lines = list(difflib.unified_diff(
+                held_content.splitlines(keepends=True),
+                disk_content.splitlines(keepends=True),
+                fromfile=f"{rel_path} (held at Step {step_seen})",
+                tofile=f"{rel_path} (current on disk)",
+                n=context_lines,
+            ))
+            diff_text = f"[TAIL DIFF: File '{rel_path}']\n" + "".join(_clip(l) for l in diff_lines)
+
+        if not diff_text:
+            continue
+
+        if used_chars + len(diff_text) > TAIL_DIFF_MAX_CHARS:
+            diff_text = diff_text[: TAIL_DIFF_MAX_CHARS - used_chars] + "\n...[truncated]"
+
+        blocks.append(diff_text)
+        shown.append(rel_path)
+        used_chars += len(diff_text)
+        if used_chars >= TAIL_DIFF_MAX_CHARS:
+            break
+
+    if not blocks:
+        return "", []
+
+    return "\n\n" + "\n\n".join(blocks), shown
+
+
+def apply_tail_diff(
+    messages: List[Dict[str, Any]],
+    bindings: List[object],
+    workspace_root: str = ".",
+    line_numbered: bool = True,
+) -> List[Dict[str, Any]]:
+    """Transform context by appending net diffs of stale files to prompt tail.
+
+    Crucially:
+    - messages[:-1] is NEVER touched, guaranteeing 100% prefix KV-cache reuse.
+    - Only files that are currently stale are diffed against the agent's held view.
+    - The diff is appended to the tail message.
+    """
+    transformed = copy.deepcopy(messages)
+    if not transformed:
+        return transformed
+
+    # Find distinct stale files
+    latest_by_file: Dict[str, object] = {}
+    for b in bindings:
+        if getattr(b, "is_invalid", False):
+            latest_by_file[getattr(b, "file_path", "")] = b
+
+    if not latest_by_file:
+        return transformed
+
+    diff_blocks: List[str] = []
+    for f_path, binding in latest_by_file.items():
+        abs_p = os.path.join(workspace_root, f_path) if not os.path.isabs(f_path) else f_path
+        if os.path.exists(abs_p) and os.path.isfile(abs_p):
+            try:
+                with open(abs_p, "r", encoding="utf-8", errors="replace") as f:
+                    disk_content = f.read()
+                held_content = getattr(binding, "file_content", None) or getattr(binding, "raw_content", None)
+                if held_content is None or held_content == disk_content:
+                    continue
+
+                step_seen = getattr(binding, "step_id", None)
+                inval_step = getattr(binding, "invalidation_step", None)
+
+                if line_numbered:
+                    diff_block = format_line_numbered_diff(
+                        held_content=held_content,
+                        disk_content=disk_content,
+                        filename=f_path,
+                        context=TAIL_DIFF_CONTEXT,
+                        step_seen=step_seen,
+                        current_step=inval_step,
+                    )
+                else:
+                    diff_lines = list(difflib.unified_diff(
+                        held_content.splitlines(keepends=True),
+                        disk_content.splitlines(keepends=True),
+                        fromfile=f"{f_path} (held at Step {step_seen})",
+                        tofile=f"{f_path} (current on disk at Step {inval_step})",
+                        n=TAIL_DIFF_CONTEXT,
+                    ))
+                    diff_block = f"[TAIL DIFF: File '{f_path}']\n" + "".join(_clip(l) for l in diff_lines)
+
+                if diff_block:
+                    diff_blocks.append(diff_block)
+            except Exception:
+                pass
+
+    if diff_blocks:
+        forwarding_text = "\n\n" + "\n\n".join(diff_blocks)
+        if transformed[-1].get("role") in ["user", "tool"]:
+            transformed[-1]["content"] += forwarding_text
+        else:
+            transformed.append({"role": "user", "content": forwarding_text.strip()})
+
+    return transformed
+
+
+def line_number_note(path, base, new, limit=4):
+    """Every stretch of the model's last whole-file view of `path` that has moved since, with its
+    offset. Counted from that one view, so offsets from several writes add up instead of each being
+    stated against the previous block (which, in a 60-run test, led agents to apply a shift twice or
+    miss one; see docs/results/shift_test_anthropic_claude-sonnet-5.md)."""
+    moved = [(i1 + 1, i2, j1 + 1, j2, j1 - i1) for tag, i1, i2, j1, j2 in
+             difflib.SequenceMatcher(None, base.splitlines(), new.splitlines(), autojunk=False).get_opcodes()
+             if tag == "equal" and j1 != i1]
+    if not moved:
+        return ""
+    parts = [f"lines {a}-{b} are now {c}-{d} ({o:+d})" for a, b, c, d, o in moved[:limit]]
+    if len(moved) > limit:
+        parts.append(f"and {len(moved) - limit} more moved stretches")
+    return f"[LINE NUMBERS: since your last full view of '{path}': " + "; ".join(parts) + "]"

align_agent/writethrough/_lib/wt_src/harness/viewport.py

@@ -0,0 +1,220 @@
+"""The write-through viewport fix, decoupled from any one agent scaffold.
+
+This is the entire mechanism behind Arm 9 (write-through viewport): after a
+step writes a file, compute a small line-numbered window centered on the
+edited region and hand it back as text to append to that step's tool output.
+Unlike retroactive prompt-rewriting arms, this never touches earlier turns --
+the caller appends the returned text to the *current* step's own output,
+before it enters the message history, so the transcript stays append-only
+and prefix caches stay valid.
+
+Nothing here is specific to mini-SWE-agent or to any particular action
+syntax. The three inputs are generic: a workspace directory, the relative
+paths a step wrote (however the caller detected that -- a filesystem
+snapshot diff is the recommended method: `os.walk` the workspace before and
+after the step, compare (mtime_ns, size) per file, and diff the two maps.
+Command-text parsing cannot keep up with the real range of ways a step can
+write a file: sed -i, an editor tool, a heredoc, a Python script that opens
+the file itself), and the file's content immediately before the step, so the
+edited region can be located.
+
+Minimal wiring pattern for a new scaffold:
+
+    before = snapshot_workspace(workspace_dir)
+    before_contents = {p: read(p) for p in referenced_paths}
+    ... run the step ...
+    after = snapshot_workspace(workspace_dir)
+    writes = sorted(p for p, meta in after.items() if before.get(p) != meta)
+    if writes:
+        step_output += viewport_echo(workspace_dir, writes, freshness_hook, before_contents)
+
+`freshness_hook` is optional: pass `None` (or any object with an empty
+`.bindings` list) if the caller doesn't already track per-file observation
+history. Its only use here is as a fallback source for a file's prior
+content when the caller didn't capture `before_contents` for a path that
+turns out to have been written -- with no fallback available, the viewport
+simply centers on the file's midpoint instead of the edited region.
+"""
+
+import os
+import subprocess
+from typing import Dict, List, Optional, Protocol, Tuple
+
+VIEWPORT_HALF = 25  # lines above and below the edit centre
+# Bounds (harness v11). The viewport is appended after the observation template
+# has folded the command's output, so nothing else limits it. Without them,
+# `npm test` writing coverage files (one 2.85M-character line) and
+# `git checkout <rev> -- src/` each produced a single observation of millions
+# of characters. The total matches the template's 10,000-character fold.
+VIEWPORT_MAX_FILES = 3
+VIEWPORT_MAX_LINE = 200
+VIEWPORT_MAX_CHARS = 10_000
+
+
+def snapshot_workspace(workspace_dir: str, skip_dirs: Optional[set] = None) -> Dict[str, Tuple[int, int]]:
+    """Map every workspace file to (mtime_ns, size).
+
+    Used to detect writes by diffing before/after a step. Inferring writes
+    from command text cannot keep up with the shell surface agents actually
+    use (sed -i, python scripts that open(...,'w'), patch, cp, tee, editors),
+    and missing a write means a stale binding is never invalidated, which
+    silently zeroes out the measurement.
+    """
+    skip = skip_dirs or {".git", "__pycache__", "node_modules", ".egg-info"}
+    snap: Dict[str, Tuple[int, int]] = {}
+    for root, dirs, files in os.walk(workspace_dir):
+        dirs[:] = [d for d in dirs if d not in skip]
+        for name in files:
+            full = os.path.join(root, name)
+            try:
+                st = os.stat(full)
+            except OSError:
+                continue
+            snap[os.path.relpath(full, workspace_dir)] = (st.st_mtime_ns, st.st_size)
+    return snap
+
+
+def diff_snapshots(before: Dict[str, Tuple[int, int]], after: Dict[str, Tuple[int, int]]) -> List[str]:
+    """Files created or modified between two snapshots."""
+    return sorted(p for p, meta in after.items() if before.get(p) != meta)
+
+
+class _BindingsSource(Protocol):
+    bindings: List[object]  # each binding needs .file_path and .file_content
+
+
+def _is_binary(path: str) -> bool:
+    try:
+        with open(path, "rb") as f:
+            return b"\0" in f.read(8192)
+    except OSError:
+        return True
+
+
+def _ignored(workspace_dir: str, paths: List[str]) -> set:
+    """The paths git ignores in this workspace: generated output (coverage,
+    build artefacts, dependencies), not file state the agent acts on. Empty
+    when the workspace is not a git repository."""
+    if not paths:
+        return set()
+    try:
+        res = subprocess.run(["git", "-C", workspace_dir, "check-ignore", "--stdin"], input="\n".join(paths),
+                             capture_output=True, text=True, timeout=30)
+    except (OSError, subprocess.SubprocessError):
+        return set()
+    return set(res.stdout.split("\n")) if res.returncode in (0, 1) else set()
+
+
+def _clip(line: str) -> str:
+    body = line.rstrip("\n")
+    if len(body) <= VIEWPORT_MAX_LINE:
+        return line
+    tail = "\n" if line.endswith("\n") else ""
+    return f"{body[:VIEWPORT_MAX_LINE]} ...[{len(body) - VIEWPORT_MAX_LINE} more characters]{tail}"
+
+
+def viewport_blocks(
+    workspace_dir: str,
+    writes: List[str],
+    freshness_hook: Optional[_BindingsSource] = None,
+    before_contents: Optional[Dict[str, str]] = None,
+) -> Tuple[str, List[str]]:
+    """The viewport text for a step's writes, and the files it shows.
+
+    A line-numbered window onto each just-written file, centered on the edit.
+    `writes` are workspace-relative paths a step wrote (see module docstring
+    for how to detect these). `before_contents` maps a subset of those paths
+    to their content immediately before the step, used to locate the edited
+    region; a path without an entry there falls back to the most recent
+    binding in `freshness_hook.bindings` for that path, then to the file's
+    midpoint if neither is available.
+
+    At most VIEWPORT_MAX_FILES files are shown, lines are clipped to
+    VIEWPORT_MAX_LINE characters and the whole to VIEWPORT_MAX_CHARS; files
+    the agent had read come first, and the rest are named in a closing line.
+    Binary files are skipped. Only the returned files may be registered as
+    seen: a written file the bounds left out was not shown to the agent.
+    """
+    if not writes:
+        return "", []
+
+    bindings = getattr(freshness_hook, "bindings", None) or []
+    ignored = _ignored(workspace_dir, list(writes))
+    writes = [w for w in writes if w not in ignored]
+    known = set(before_contents or ()) | {getattr(b, "file_path", None) for b in bindings}
+    blocks: List[str] = []
+    shown: List[str] = []
+    left_out: List[str] = []
+    used = 0
+    for rel_path in sorted(writes, key=lambda p: (p not in known, p)):
+        abs_path = os.path.join(workspace_dir, rel_path)
+        if not os.path.isfile(abs_path) or _is_binary(abs_path):
+            continue
+        if len(shown) >= VIEWPORT_MAX_FILES:
+            left_out.append(rel_path)
+            continue
+        try:
+            with open(abs_path, "r", encoding="utf-8", errors="replace") as f:
+                lines = f.readlines()
+        except OSError:
+            continue
+
+        total = len(lines)
+        # Find the centre of the edit region by diffing against the
+        # before-snapshot content. Fall back to the file midpoint.
+        centre = total // 2
+        old_content = None
+        if before_contents and rel_path in before_contents:
+            old_content = before_contents[rel_path]
+        else:
+            for b in reversed(bindings):
+                if getattr(b, "file_path", None) == rel_path and getattr(b, "file_content", None):
+                    old_content = b.file_content
+                    break
+
+        if old_content is not None:
+            old_lines = old_content.splitlines(keepends=True)
+            first_diff = None
+            for i, (a, b) in enumerate(zip(old_lines, lines)):
+                if a != b:
+                    first_diff = i
+                    break
+            if first_diff is None and len(old_lines) != total:
+                first_diff = min(len(old_lines), total)
+            if first_diff is not None:
+                centre = first_diff
+
+        half = VIEWPORT_HALF
+        if total <= half * 2:
+            start, end = 0, total
+        else:
+            start = max(0, centre - half)
+            end = min(total, start + half * 2)
+            if end - start < half * 2:
+                start = max(0, end - half * 2)
+
+        viewport = "".join(f"{i}\t{_clip(line)}" for i, line in enumerate(lines[start:end], start=start + 1))
+        block = f"[VIEWPORT (lines {start + 1}-{end} of {total}): {rel_path}]\n{viewport}"
+        if used + len(block) > VIEWPORT_MAX_CHARS:
+            left_out.append(rel_path)
+            continue
+        blocks.append(block)
+        shown.append(rel_path)
+        used += len(block)
+
+    if left_out:
+        names = ", ".join(left_out[:10]) + (", ..." if len(left_out) > 10 else "")
+        blocks.append(f"[{len(left_out)} more written files not shown: {names}]")
+    if not blocks:
+        return "", []
+    return "\n\n" + "\n\n".join(blocks), shown
+
+
+def viewport_echo(
+    workspace_dir: str,
+    writes: List[str],
+    freshness_hook: Optional[_BindingsSource] = None,
+    before_contents: Optional[Dict[str, str]] = None,
+) -> str:
+    """The text of `viewport_blocks` alone."""
+    return viewport_blocks(workspace_dir, writes, freshness_hook, before_contents)[0]

align_agent/writethrough/_lib/wt_src/metrics/__init__.py

@@ -0,0 +1,38 @@
+"""Metrics package for staleness replay and statistical analysis.
+
+The statistics helpers pull in statsmodels, scipy and numpy. Importing them
+here made every consumer of this package pay that cost, including the
+experiment runner, which needs nothing but the corruption oracles: on one
+machine a scipy/numpy version mismatch in the active interpreter turned
+`from wt_src.metrics.corruption_oracles import ...` into an import error, which
+has nothing to do with what the caller asked for. They are resolved on first
+attribute access instead.
+
+The paper's numbers come from src/metrics/replay.py (one stale-edit
+definition for both research questions) via scripts/run_phase1_analysis.py
+and scripts/recompute_metrics.py.
+"""
+
+from typing import Any
+
+_LAZY = {
+    "compute_windowed_odds_ratios": ".statistics",
+    "fit_length_controlled_logistic_regression": ".statistics",
+    "fit_stale_edit_association": ".statistics",
+}
+
+
+def __getattr__(name: str) -> Any:
+    module_name = _LAZY.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    return getattr(import_module(module_name, __name__), name)
+
+
+__all__ = [
+    "compute_windowed_odds_ratios",
+    "fit_length_controlled_logistic_regression",
+    "fit_stale_edit_association",
+]