alysis-code 0.13.0__py3-none-any.whl

alysis_code/agent/turn/interventions.py

@@ -0,0 +1,65 @@
+"""Per-turn controller intervention telemetry.
+
+The headline target is controller_interventions_total ≈ 0 on clean successful turns.
+"""
+
+from __future__ import annotations
+
+from collections import Counter
+from collections.abc import Mapping
+from typing import Any
+
+HEADLINE_EXCLUDED_CLASSES = frozenset(
+    {
+        "context_setup",
+        "deadline_directive",
+        "safety_block",
+    }
+)
+
+
+class ControllerInterventionTracker:
+    def __init__(self, store: Any) -> None:
+        self._store = store
+        self._counts: Counter[str] = Counter()
+        self._headline_total = 0
+
+    @property
+    def headline_total(self) -> int:
+        return self._headline_total
+
+    def record(
+        self,
+        intervention_class: str,
+        detail: str,
+        *,
+        step: int | None = None,
+        metadata: Mapping[str, Any] | None = None,
+        headline_counted: bool | None = None,
+    ) -> None:
+        normalized_class = str(intervention_class or "").strip() or "other"
+        normalized_detail = str(detail or "").strip() or "unspecified"
+        counted = (
+            normalized_class not in HEADLINE_EXCLUDED_CLASSES
+            if headline_counted is None
+            else bool(headline_counted)
+        )
+        self._counts[normalized_class] += 1
+        if counted:
+            self._headline_total += 1
+        payload: dict[str, Any] = {
+            "class": normalized_class,
+            "detail": normalized_detail,
+            "step": step,
+            "headline_counted": counted,
+            "controller_interventions_total": self._headline_total,
+        }
+        if metadata:
+            payload["metadata"] = dict(metadata)
+        self._store.append("controller_intervention", payload)
+
+    def payload(self) -> dict[str, Any]:
+        return {
+            "total": self._headline_total,
+            "by_class": dict(sorted(self._counts.items())),
+        }

alysis_code/agent/turn/read_cache.py

@@ -0,0 +1,420 @@
+from __future__ import annotations
+
+import copy
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from ..prompt_context import _normalize_repo_relative_hint_path
+from ..tools_assembly import ToolDef
+
+_SAME_BATCH_FS_READ_DEFAULT_MAX_BYTES = 20_000
+_SAME_BATCH_FS_READ_LINES_DEFAULT_MAX_LINES = 200
+# Mirrors tools.fs._DEFAULT_READ_LINES_MAX_BYTES: an absent max_bytes argument
+# keys and caps identically to the tool's own default ceiling.
+_SAME_BATCH_FS_READ_LINES_DEFAULT_MAX_BYTES = 48_000
+_SAME_BATCH_READ_CACHE_SAFE_TOOL_NAMES = {
+    "fs_read",
+    "fs_read_lines",
+    "fs_list",
+    "web_fetch",
+    "web_search",
+    "symbol_search",
+    "test_discover",
+    "repo_map",
+    "search_rg",
+    "history_search",
+    "skill_read",
+    "git_status",
+    "git_diff",
+    "git_history",
+}
+
+
+@dataclass(frozen=True)
+class _SameBatchFsReadRecord:
+    path_key: str
+    raw_lines: tuple[str, ...]
+    result: dict[str, Any]
+
+
+@dataclass(frozen=True)
+class _SameBatchFsReadLinesRecord:
+    path_key: str
+    start_line: int
+    end_line: int
+    total_lines: int | None
+    truncated: bool
+    include_line_numbers: bool
+    content_lines: tuple[str, ...]
+    result: dict[str, Any]
+
+
+@dataclass
+class _SameBatchReadReuseCache:
+    exact_fs_reads: dict[tuple[str, int, bool], dict[str, Any]] = field(default_factory=dict)
+    exact_fs_read_lines: dict[tuple[str, int, int | None, int, bool, int], dict[str, Any]] = field(
+        default_factory=dict
+    )
+    full_fs_reads: dict[str, _SameBatchFsReadRecord] = field(default_factory=dict)
+    fs_read_lines_by_path: dict[str, list[_SameBatchFsReadLinesRecord]] = field(
+        default_factory=dict
+    )
+
+    def clear(self) -> None:
+        self.exact_fs_reads.clear()
+        self.exact_fs_read_lines.clear()
+        self.full_fs_reads.clear()
+        self.fs_read_lines_by_path.clear()
+
+
+def _same_batch_read_path_key(*, root: Path, raw_path: Any) -> str | None:
+    normalized = _normalize_repo_relative_hint_path(root=root, raw=str(raw_path or ""))
+    if normalized:
+        return normalized
+    candidate = str(raw_path or "").strip().replace("\\", "/")
+    while candidate.startswith("./"):
+        candidate = candidate[2:]
+    if not candidate:
+        return None
+    normalized_candidate = os.path.normpath(candidate).replace("\\", "/")
+    if normalized_candidate in {"", ".", ".."} or normalized_candidate.startswith("../"):
+        return None
+    if normalized_candidate.startswith("/"):
+        normalized_candidate = normalized_candidate[1:]
+    return normalized_candidate or None
+
+
+def _split_text_preserving_lines(text: str) -> tuple[str, ...]:
+    if not text:
+        return ()
+    return tuple(text.splitlines(keepends=True))
+
+
+def _coerce_fs_read_request(
+    *,
+    root: Path,
+    arguments: dict[str, Any],
+) -> tuple[str, str, int, bool] | None:
+    raw_path = str(arguments.get("path") or "")
+    path_key = _same_batch_read_path_key(root=root, raw_path=raw_path)
+    if not path_key:
+        return None
+    raw_max_bytes = arguments.get("max_bytes")
+    max_bytes = (
+        _SAME_BATCH_FS_READ_DEFAULT_MAX_BYTES if raw_max_bytes is None else int(raw_max_bytes)
+    )
+    return (
+        path_key,
+        raw_path,
+        max_bytes,
+        bool(arguments.get("allow_derived", False)),
+    )
+
+
+def _coerce_fs_read_lines_request(
+    *,
+    root: Path,
+    arguments: dict[str, Any],
+) -> tuple[str, str, int, int | None, int, bool, int] | None:
+    raw_path = str(arguments.get("path") or "")
+    path_key = _same_batch_read_path_key(root=root, raw_path=raw_path)
+    if not path_key:
+        return None
+    start_line = int(arguments["start_line"]) if arguments.get("start_line") is not None else 0
+    requested_end_line = (
+        int(arguments["end_line"]) if arguments.get("end_line") is not None else None
+    )
+    max_lines = (
+        int(arguments["max_lines"])
+        if arguments.get("max_lines") is not None
+        else _SAME_BATCH_FS_READ_LINES_DEFAULT_MAX_LINES
+    )
+    include_line_numbers = bool(arguments.get("include_line_numbers", True))
+    raw_max_bytes = arguments.get("max_bytes")
+    if raw_max_bytes is None:
+        max_bytes = _SAME_BATCH_FS_READ_LINES_DEFAULT_MAX_BYTES
+    else:
+        max_bytes = int(raw_max_bytes)
+        if max_bytes < 1:
+            # Invalid ceiling: never serve it from cache - the real tool owns
+            # the FsError for out-of-range values.
+            return None
+    return (
+        path_key,
+        raw_path,
+        start_line,
+        requested_end_line,
+        max_lines,
+        include_line_numbers,
+        max_bytes,
+    )
+
+
+def _build_fs_read_lines_result_from_full_fs_read(
+    *,
+    raw_path: str,
+    request: tuple[str, str, int, int | None, int, bool, int],
+    record: _SameBatchFsReadRecord,
+) -> dict[str, Any] | None:
+    _, _, start_line, requested_end_line, max_lines, include_line_numbers, max_bytes = request
+    total_lines = len(record.raw_lines)
+    if start_line < 1 or start_line > total_lines:
+        return None
+
+    effective_end_line = start_line + max_lines - 1
+    if requested_end_line is not None:
+        effective_end_line = min(effective_end_line, requested_end_line)
+    actual_end_line = min(effective_end_line, total_lines)
+    selected_lines = record.raw_lines[start_line - 1 : actual_end_line]
+    if not selected_lines:
+        return None
+
+    if include_line_numbers:
+        content = "".join(
+            f"{lineno}: {line}"
+            for lineno, line in zip(
+                range(start_line, actual_end_line + 1), selected_lines, strict=False
+            )
+        )
+    else:
+        content = "".join(selected_lines)
+
+    if len(content.encode("utf-8")) > max_bytes:
+        # The rebuilt window would exceed the request's byte ceiling; let the
+        # real tool run and apply its own clipping rather than replicate it.
+        return None
+
+    return {
+        "path": raw_path,
+        "start_line": start_line,
+        "end_line": actual_end_line,
+        "total_lines": total_lines if actual_end_line == total_lines else None,
+        "content": content,
+        "truncated": requested_end_line is None and actual_end_line < total_lines,
+    }
+
+
+def _build_fs_read_lines_result_from_cached_range(
+    *,
+    raw_path: str,
+    request: tuple[str, str, int, int | None, int, bool, int],
+    record: _SameBatchFsReadLinesRecord,
+) -> dict[str, Any] | None:
+    _, _, start_line, requested_end_line, max_lines, include_line_numbers, max_bytes = request
+    if start_line < record.start_line:
+        return None
+    if include_line_numbers != record.include_line_numbers:
+        return None
+
+    requested_max_end = start_line + max_lines - 1
+    if requested_end_line is not None:
+        requested_max_end = min(requested_max_end, requested_end_line)
+
+    if requested_end_line is not None:
+        if requested_max_end <= record.end_line:
+            actual_end_line = requested_max_end
+        elif (
+            record.total_lines is not None
+            and start_line <= record.total_lines
+            and record.end_line == record.total_lines
+        ):
+            actual_end_line = record.total_lines
+        else:
+            return None
+    else:
+        if requested_max_end < record.end_line:
+            actual_end_line = requested_max_end
+        elif requested_max_end == record.end_line:
+            if record.total_lines is not None:
+                actual_end_line = requested_max_end
+            elif record.truncated:
+                actual_end_line = requested_max_end
+            else:
+                return None
+        elif (
+            record.total_lines is not None
+            and start_line <= record.total_lines
+            and record.end_line == record.total_lines
+        ):
+            actual_end_line = record.total_lines
+        else:
+            return None
+
+    if actual_end_line < start_line:
+        return None
+
+    start_offset = start_line - record.start_line
+    end_offset = actual_end_line - record.start_line + 1
+    selected_lines = record.content_lines[start_offset:end_offset]
+    if len(selected_lines) != (actual_end_line - start_line + 1):
+        return None
+
+    truncated = False
+    if requested_end_line is None:
+        if actual_end_line < record.end_line:
+            truncated = True
+        elif record.total_lines is not None:
+            truncated = actual_end_line < record.total_lines
+        else:
+            truncated = record.truncated
+
+    content = "".join(selected_lines)
+    if len(content.encode("utf-8")) > max_bytes:
+        # The rebuilt window would exceed the request's byte ceiling; let the
+        # real tool run and apply its own clipping rather than replicate it.
+        return None
+
+    return {
+        "path": raw_path,
+        "start_line": start_line,
+        "end_line": actual_end_line,
+        "total_lines": (
+            record.total_lines
+            if record.total_lines is not None and actual_end_line == record.total_lines
+            else None
+        ),
+        "content": content,
+        "truncated": truncated,
+    }
+
+
+def _maybe_reuse_same_batch_read_result(
+    *,
+    root: Path,
+    cache: _SameBatchReadReuseCache,
+    tool_name: str,
+    arguments: dict[str, Any],
+) -> dict[str, Any] | None:
+    if tool_name == "fs_read":
+        request = _coerce_fs_read_request(root=root, arguments=arguments)
+        if request is None:
+            return None
+        path_key, raw_path, max_bytes, allow_derived = request
+        cached = cache.exact_fs_reads.get((path_key, max_bytes, allow_derived))
+        if cached is None:
+            return None
+        reused = copy.deepcopy(cached)
+        reused["path"] = raw_path
+        return reused
+
+    if tool_name != "fs_read_lines":
+        return None
+
+    request = _coerce_fs_read_lines_request(root=root, arguments=arguments)
+    if request is None:
+        return None
+    (
+        path_key,
+        raw_path,
+        start_line,
+        requested_end_line,
+        max_lines,
+        include_line_numbers,
+        max_bytes,
+    ) = request
+    cached_exact = cache.exact_fs_read_lines.get(
+        (path_key, start_line, requested_end_line, max_lines, include_line_numbers, max_bytes)
+    )
+    if cached_exact is not None:
+        reused = copy.deepcopy(cached_exact)
+        reused["path"] = raw_path
+        return reused
+
+    full_read = cache.full_fs_reads.get(path_key)
+    if full_read is not None:
+        reused = _build_fs_read_lines_result_from_full_fs_read(
+            raw_path=raw_path,
+            request=request,
+            record=full_read,
+        )
+        if reused is not None:
+            return reused
+
+    for record in reversed(cache.fs_read_lines_by_path.get(path_key, [])):
+        reused = _build_fs_read_lines_result_from_cached_range(
+            raw_path=raw_path,
+            request=request,
+            record=record,
+        )
+        if reused is not None:
+            return reused
+    return None
+
+
+def _remember_same_batch_read_result(
+    *,
+    root: Path,
+    cache: _SameBatchReadReuseCache,
+    tool_name: str,
+    arguments: dict[str, Any],
+    result: dict[str, Any],
+) -> None:
+    if tool_name == "fs_read":
+        request = _coerce_fs_read_request(root=root, arguments=arguments)
+        if request is None:
+            return
+        path_key, _, max_bytes, allow_derived = request
+        stored = copy.deepcopy(result)
+        cache.exact_fs_reads[(path_key, max_bytes, allow_derived)] = stored
+        if bool(result.get("truncated")):
+            return
+        content = result.get("content")
+        if isinstance(content, str):
+            cache.full_fs_reads[path_key] = _SameBatchFsReadRecord(
+                path_key=path_key,
+                raw_lines=_split_text_preserving_lines(content),
+                result=stored,
+            )
+        return
+
+    if tool_name != "fs_read_lines":
+        return
+    request = _coerce_fs_read_lines_request(root=root, arguments=arguments)
+    if request is None:
+        return
+    (
+        path_key,
+        _,
+        start_line,
+        requested_end_line,
+        max_lines,
+        include_line_numbers,
+        max_bytes,
+    ) = request
+    end_line = result.get("end_line")
+    content = result.get("content")
+    if not isinstance(end_line, int) or not isinstance(content, str):
+        return
+    if bool(result.get("byte_truncated")) or bool(result.get("line_clipped")):
+        # A byte-capped window may end mid-line; reusing it to answer other
+        # range requests would silently serve incomplete lines.
+        return
+    stored = copy.deepcopy(result)
+    cache.exact_fs_read_lines[
+        (path_key, start_line, requested_end_line, max_lines, include_line_numbers, max_bytes)
+    ] = stored
+    cache.fs_read_lines_by_path.setdefault(path_key, []).append(
+        _SameBatchFsReadLinesRecord(
+            path_key=path_key,
+            start_line=start_line,
+            end_line=end_line,
+            total_lines=(
+                int(result["total_lines"]) if result.get("total_lines") is not None else None
+            ),
+            truncated=bool(result.get("truncated")),
+            include_line_numbers=include_line_numbers,
+            content_lines=_split_text_preserving_lines(content),
+            result=stored,
+        )
+    )
+
+
+def _same_batch_read_cache_should_invalidate(tool_name: str, tool: ToolDef | None) -> bool:
+    normalized = str(tool_name or "").strip()
+    if not normalized:
+        return True
+    if normalized not in _SAME_BATCH_READ_CACHE_SAFE_TOOL_NAMES:
+        return True
+    return tool is None

alysis_code/agent/turn/snapshot.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import os
+import subprocess
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from ...runtime_artifacts import is_runtime_artifact_path
+from ..prompt_context import _normalize_repo_relative_hint_path
+
+_SHELL_MUTATION_SNAPSHOT_METADATA_PREFIX = "meta"
+
+
+def _list_git_workspace_snapshot_paths(root: Path) -> set[str] | None:
+    try:
+        proc = subprocess.run(
+            [
+                "git",
+                "-C",
+                os.fspath(root),
+                "ls-files",
+                "-z",
+                "--cached",
+                "--others",
+                "--exclude-standard",
+            ],
+            check=False,
+            capture_output=True,
+        )
+    except OSError:
+        return None
+    if proc.returncode != 0:
+        return None
+
+    paths: set[str] = set()
+    stdout = proc.stdout or b""
+    raw_items: list[str | bytes]
+    if isinstance(stdout, str):
+        raw_items = stdout.split("\0")
+    else:
+        raw_items = stdout.split(b"\0")
+    for raw_item in raw_items:
+        if not raw_item:
+            continue
+        raw_path = (
+            raw_item
+            if isinstance(raw_item, str)
+            else raw_item.decode("utf-8", errors="surrogateescape")
+        )
+        normalized = _normalize_repo_relative_hint_path(
+            root=root,
+            raw=raw_path,
+        )
+        if not normalized or is_runtime_artifact_path(normalized, root=root):
+            continue
+        paths.add(normalized)
+    return paths
+
+
+def _walk_workspace_snapshot_paths(root: Path) -> set[str]:
+    root_resolved = root.resolve()
+    paths: set[str] = set()
+    for current_root, dirnames, filenames in os.walk(root_resolved):
+        current_path = Path(current_root)
+        resolved_current = current_path.resolve()
+        rel_dir = (
+            resolved_current.relative_to(root_resolved).as_posix()
+            if resolved_current != root_resolved
+            else ""
+        )
+        kept_dirnames: list[str] = []
+        for dirname in dirnames:
+            rel_candidate = dirname if not rel_dir else f"{rel_dir}/{dirname}"
+            normalized = _normalize_repo_relative_hint_path(root=root, raw=rel_candidate)
+            if normalized and is_runtime_artifact_path(normalized, root=root):
+                continue
+            kept_dirnames.append(dirname)
+        dirnames[:] = kept_dirnames
+        for filename in filenames:
+            rel_candidate = filename if not rel_dir else f"{rel_dir}/{filename}"
+            normalized = _normalize_repo_relative_hint_path(root=root, raw=rel_candidate)
+            if not normalized or is_runtime_artifact_path(normalized, root=root):
+                continue
+            paths.add(normalized)
+    return paths
+
+
+def _workspace_snapshot_signature(path: Path) -> str | None:
+    try:
+        stat = path.stat()
+    except OSError:
+        return None
+    if not path.is_file():
+        return None
+    ctime_ns = getattr(stat, "st_ctime_ns", int(stat.st_ctime * 1_000_000_000))
+    return (
+        f"{_SHELL_MUTATION_SNAPSHOT_METADATA_PREFIX}:{stat.st_size}:{stat.st_mtime_ns}:{ctime_ns}"
+    )
+
+
+def _snapshot_workspace_for_command_mutation_detection(root: Path) -> dict[str, str]:
+    candidate_paths = _list_git_workspace_snapshot_paths(root)
+    if candidate_paths is None:
+        candidate_paths = _walk_workspace_snapshot_paths(root)
+    snapshot: dict[str, str] = {}
+    for rel_path in sorted(candidate_paths):
+        signature = _workspace_snapshot_signature(root / rel_path)
+        if signature is None:
+            continue
+        snapshot[rel_path] = signature
+    return snapshot
+
+
+def _path_matches_snapshot_ignore(
+    rel_path: str,
+    *,
+    ignored_paths: set[str],
+) -> bool:
+    return any(
+        rel_path == ignored or rel_path.startswith(f"{ignored}/") for ignored in ignored_paths
+    )
+
+
+def _normalize_snapshot_ignore_paths(root: Path, paths: Iterable[Path]) -> set[str]:
+    ignored: set[str] = set()
+    resolved_root = root.resolve()
+    for path in paths:
+        try:
+            rel_path = path.resolve().relative_to(resolved_root)
+        except ValueError:
+            continue
+        normalized = _normalize_repo_relative_hint_path(root=root, raw=os.fspath(rel_path))
+        if normalized:
+            ignored.add(normalized)
+    return ignored
+
+
+def _detect_command_mutation_paths(
+    *,
+    before: dict[str, str],
+    after: dict[str, str],
+) -> list[str]:
+    changed = {
+        rel_path
+        for rel_path in (set(before) | set(after))
+        if before.get(rel_path) != after.get(rel_path)
+    }
+    return sorted(changed)
+
+
+def _run_with_command_mutation_detection(
+    *,
+    root: Path,
+    enabled: bool,
+    ignored_paths: Iterable[Path] = (),
+    operation: Callable[[], Any],
+) -> tuple[Any, list[str]]:
+    if not enabled:
+        return operation(), []
+    ignored = _normalize_snapshot_ignore_paths(root, ignored_paths)
+    before_snapshot = {
+        rel_path: signature
+        for rel_path, signature in _snapshot_workspace_for_command_mutation_detection(root).items()
+        if not _path_matches_snapshot_ignore(rel_path, ignored_paths=ignored)
+    }
+    result = operation()
+    after_snapshot = {
+        rel_path: signature
+        for rel_path, signature in _snapshot_workspace_for_command_mutation_detection(root).items()
+        if not _path_matches_snapshot_ignore(rel_path, ignored_paths=ignored)
+    }
+    return (
+        result,
+        _detect_command_mutation_paths(
+            before=before_snapshot,
+            after=after_snapshot,
+        ),
+    )