localcode 0.4.0__py3-none-macosx_13_0_arm64.whl

localcode/tools/read_file.py

@@ -0,0 +1,261 @@
+"""read_file — read a file with optional line offset/limit."""
+from __future__ import annotations
+
+from .base import ToolContext
+
+
+DEFAULT_LIMIT = 240
+MAX_DEFAULT_CHARS = 12_000
+
+
+def _dynamic_read_defaults(ctx: ToolContext) -> tuple[int, int]:
+    """(default_line_limit, max_default_chars), scaled to the model's real
+    context window. read_file is the primary code-ingestion path: on a 256K
+    window the fixed 240-line / 12K-char default forces needless pagination and
+    re-reads where the machine has the MOST room. Scale up to ~6% of the window
+    in chars (and lines proportionally), floored at the static defaults so a
+    16 GB Mac (small window) is byte-identical to before.
+    """
+    try:
+        ctx_tokens = int(ctx.app.engine._target_num_ctx())
+    except Exception:
+        ctx_tokens = 0
+    if not ctx_tokens:
+        return DEFAULT_LIMIT, MAX_DEFAULT_CHARS
+    max_chars = max(MAX_DEFAULT_CHARS, int(ctx_tokens * 3.5 * 0.06))
+    # Keep the historical ~50 chars/line ratio between the two defaults.
+    line_limit = max(DEFAULT_LIMIT, max_chars // 50)
+    return line_limit, max_chars
+
+SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "read_file",
+        "description": "Read a file. You MUST read before editing. Returns content with line numbers.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "File path relative to repo root"},
+                "offset": {"type": "integer", "description": "Start line (0-based). Optional."},
+                "limit": {
+                    "type": "integer",
+                    "description": (
+                        "Max lines. Default 240. Use a small targeted range "
+                        "for large files; only request a larger limit when the "
+                        "whole file is genuinely needed."
+                    ),
+                },
+            },
+            "required": ["path"],
+        },
+    },
+}
+
+
+# Fuzzy-match ratio at/above which we AUTO-READ the real file instead of
+# merely suggesting it. 0.85 is high enough that only genuine typos /
+# case-variants of one real name match (e.g. a dropped letter or wrong
+# case), not two distinct files that happen to be somewhat similar.
+AUTO_READ_RATIO = 0.85
+
+
+def _list_dir_candidates(missing):
+    """(candidates, base) — every file under the nearest existing ancestor of
+    `missing`. Walk up to 6 levels so a wrong path segment deep in the tree
+    still resolves to a searchable directory. Capped at 4000 files."""
+    from pathlib import Path
+    missing = Path(missing)
+    base = missing.parent
+    for _ in range(6):
+        if base.exists():
+            break
+        base = base.parent
+    if not base.exists():
+        return [], None
+    candidates = []
+    for p in base.rglob("*"):
+        if p.is_file():
+            candidates.append(p)
+        if len(candidates) > 4000:
+            break
+    return candidates, base
+
+
+def _confident_match(missing):
+    """Return the ONE real file `missing` is almost certainly a typo of, else
+    None. Authoritative (used to auto-read), so it only fires when unambiguous:
+
+      • exactly one file whose basename equals `missing`'s case-insensitively
+        (a pure case/typo of a unique name — gitHub→Github, README.MD→readme.md), OR
+      • exactly one file whose basename fuzzy-matches at ratio ≥ AUTO_READ_RATIO.
+
+    Requiring the winner to be UNIQUE prevents auto-reading the wrong one of
+    several same-named files in different dirs — that stays a soft suggestion.
+    """
+    import difflib
+    from pathlib import Path
+    try:
+        candidates, _ = _list_dir_candidates(missing)
+        if not candidates:
+            return None
+        name = Path(missing).name
+        # Pure case/typo of a unique basename → definitely that file.
+        same = [p for p in candidates if p.name.lower() == name.lower()]
+        if len(same) == 1:
+            return same[0]
+        if len(same) > 1:
+            return None  # ambiguous by name — don't auto-pick.
+        # High-confidence fuzzy basename match, and it must be unique.
+        names = [p.name for p in candidates]
+        close = difflib.get_close_matches(name, names, n=1, cutoff=AUTO_READ_RATIO)
+        if close:
+            hits = [p for p in candidates if p.name == close[0]]
+            if len(hits) == 1:
+                return hits[0]
+    except Exception:
+        pass
+    return None
+
+
+def _suggest_path(missing) -> str:
+    """Suggest the real file when the model gave a typo'd/wrong-case path.
+
+    Walk up to the nearest existing ancestor dir and fuzzy-match the missing
+    filename (and its path segments) against what's actually there. Lower-
+    confidence sibling of `_confident_match`: used only when we're NOT sure
+    enough to auto-read, so it stays a hint the model can act on.
+    """
+    import difflib
+    from pathlib import Path
+    try:
+        missing = Path(missing)
+        name = missing.name
+        candidates, base = _list_dir_candidates(missing)
+        if not candidates:
+            return ""
+        names = [p.name for p in candidates]
+        close = difflib.get_close_matches(name, names, n=1, cutoff=0.6)
+        if close:
+            match = next(p for p in candidates if p.name == close[0])
+            return f"Did you mean: {match} — read THAT exact path (don't guess variants)."
+    except Exception:
+        pass
+    return ""
+
+
+def execute(ctx: ToolContext, args: dict) -> str:
+    if "path" not in args:
+        return "Error: 'path' argument is required for read_file."
+    requested = args["path"]
+    path = ctx.resolve_path(requested)
+    note = ""
+    source_disp = str(requested)
+    if not path.exists():
+        # A small model invents misspelled/wrong-case paths (a dropped letter,
+        # gitHub/github/Github) and, getting a bare "not found", retries with
+        # ANOTHER wrong variant forever (dedup can't collapse differing typos).
+        real = _confident_match(path)
+        if real is None:
+            # Not confident enough to auto-read — hand back the best soft hint.
+            hint = _suggest_path(path)
+            return f"File not found: {requested}" + (f"\n{hint}" if hint else "")
+        # AUTHORITATIVE recovery: `requested` is unambiguously a typo/case-
+        # variant of exactly one real file. Read THAT file now instead of
+        # bouncing the model back with a suggestion it can ignore (which is
+        # what fuels the 20+-retry not-found death loop). The note pins the
+        # correct path so the next call uses it directly.
+        try:
+            source_disp = str(real.relative_to(ctx.repo))
+        except Exception:
+            source_disp = str(real)
+        note = (
+            f"[read {source_disp} instead of '{requested}' — that path does not "
+            f"exist and this is the only close match. Use '{source_disp}' "
+            "exactly from now on; do NOT guess more spellings.]\n\n"
+        )
+        path = real
+    if path.is_dir():
+        # The model routinely read_file's a directory (confusing it with
+        # list_files), gets IsADirectoryError, and burns a whole round before
+        # retrying with list_files. Just hand back the listing + a nudge so the
+        # round is productive instead of wasted.
+        try:
+            entries = sorted(
+                p.name + ("/" if p.is_dir() else "") for p in path.iterdir()
+            )
+        except Exception as e:
+            return f"Error: '{source_disp}' is a directory and could not be listed: {e}"
+        shown = entries[:200]
+        more = f"\n  … ({len(entries) - len(shown)} more)" if len(entries) > len(shown) else ""
+        body = "\n".join(f"  {e}" for e in shown) or "  (empty)"
+        return (
+            f"'{source_disp}' is a directory, not a file ({len(entries)} entries). "
+            f"read_file needs a FILE path; use list_files for directories. Contents:\n"
+            f"{body}{more}"
+        )
+    # Binary guard: reading an image / .gguf / compiled artifact would dump raw
+    # bytes into the model's context (garbage that wastes tokens and can derail
+    # it). Detect via a NUL byte in the head — the standard text/binary
+    # heuristic — reading only the first 8 KB so a multi-GB file stays cheap.
+    try:
+        with open(path, "rb") as _fh:
+            _head = _fh.read(8192)
+        if b"\x00" in _head:
+            _sz = path.stat().st_size
+            return (
+                f"'{source_disp}' is a BINARY file ({_sz} bytes) — not shown, "
+                f"because reading it would dump raw bytes into context. It is not "
+                f"a text file; open it with the appropriate tool if you need it."
+            )
+    except Exception:
+        pass
+    content = path.read_text(errors="replace")
+    lines = content.splitlines()
+    default_limit, max_default_chars = _dynamic_read_defaults(ctx)
+    offset = args.get("offset", 0)
+    explicit_limit = "limit" in args
+    limit = args.get("limit", default_limit)
+    # A read is "full" (satisfies the read-before-edit guard) only when it
+    # starts at the top AND returns every line untruncated. offset>0 or any
+    # truncation below flips this to a partial view.
+    _full_read = (not offset) and (len(lines) <= offset + limit)
+    selected = lines[offset:offset + limit]
+    numbered = [f"{i + offset + 1}\t{line}" for i, line in enumerate(selected)]
+    result = "\n".join(numbered)
+    if len(lines) > offset + limit:
+        result += f"\n\n[{len(lines) - offset - limit} more lines — use offset={offset + limit} to continue]"
+    if not explicit_limit and len(result) > max_default_chars:
+        kept: list[str] = []
+        total = 0
+        for line in numbered:
+            total += len(line) + 1
+            if total > max_default_chars:
+                break
+            kept.append(line)
+        result = "\n".join(kept)
+        remaining_from_line = offset + len(kept)
+        result += (
+            f"\n\n[Large file summarized at {max_default_chars} chars. "
+            f"File has {len(lines)} lines; continue with "
+            f"offset={remaining_from_line}, limit={default_limit}, or request "
+            "a focused smaller range around the symbol you need.]"
+        )
+        _full_read = False  # char-truncated: the model has not seen the whole file
+    # Record this read for the read-before-edit staleness guard (edit_file /
+    # write_file / multi_edit consult it). Best-effort; never fail a read.
+    try:
+        from . import read_state
+        read_state.record_read(ctx.app, path, full=_full_read)
+    except Exception:
+        pass
+    # Prompt-injection defence: wrap untrusted file content in explicit
+    # data/instruction separator markers so the model knows this text
+    # is DATA, not commands. Signature detector flags common injection
+    # phrases (IGNORE ALL PRIOR INSTRUCTIONS, etc.) with a visible
+    # warning before the content. See src/localcode/injection_defense.py.
+    from ..injection_defense import wrap_untrusted
+    return note + wrap_untrusted(result, source=source_disp)
+
+
+def is_concurrency_safe(args: dict) -> bool:
+    return True

localcode/tools/read_state.py

@@ -0,0 +1,223 @@
+"""Per-session read-state registry — the read-before-edit staleness guard.
+
+Ports claude-code's `FileEditTool.readFileState` pattern (a map of
+absolute-path -> {content-hash, mtime, full/partial}) and folds in the
+compare-on-write idea from codex/opencode V2 (`writeIfUnchanged`).
+
+Why a guard at all
+------------------
+A surgical edit (`edit_file`/`multi_edit`) only makes sense against the
+CURRENT bytes of a file. If the model never read the file, or read it and
+the file has since changed on disk (its own earlier write, a formatter, an
+AV/cloud-sync touch, another process), then `old_string` is being matched
+against text the model has NOT seen — the classic silent-clobber failure.
+claude-code refuses such edits until the file is (re)read.
+
+Two subtleties copied from claude-code
+--------------------------------------
+* A PARTIAL read (offset/limit or a truncated large-file read) does NOT
+  satisfy the guard — the model hasn't seen the whole file, so its anchor
+  may sit in an unseen region.
+* CONTENT-EQUALITY fallback: if the mtime advanced but the bytes are
+  byte-identical to what was read, we do NOT false-reject (a formatter or
+  AV touch that rewrites the file with the same content bumps mtime).
+
+Session scoping
+---------------
+State lives on the app object (`app._edit_read_state`), so it is naturally
+scoped to one agent session and a fresh app (e.g. a unit test that calls
+`edit_file` directly) starts empty. The guard only ENFORCES once the
+session has recorded at least one read (`is_armed`): with no read on record
+there is no freshness baseline, so enforcing would be pure friction. In a
+real session `read_file` fires constantly, arming the guard immediately.
+
+After a successful write/edit the tool calls `record_write`, so the model's
+own writes refresh the baseline and never trip the guard on the next round.
+"""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+_ATTR = "_edit_read_state"
+
+# Files larger than this are not hashed (staleness still works off mtime;
+# only the content-equality fallback is skipped for very large files).
+_MAX_HASH_BYTES = 4 * 1024 * 1024
+
+
+def _registry(app: Any) -> dict[str, dict]:
+    reg = getattr(app, _ATTR, None)
+    if not isinstance(reg, dict):
+        reg = {}
+        try:
+            setattr(app, _ATTR, reg)
+        except Exception:
+            # Slotted/frozen app: fall back to a module-level per-id map so
+            # the guard still functions instead of silently disabling.
+            reg = _fallback_registry(app)
+    return reg
+
+
+_FALLBACK: dict[int, dict] = {}
+
+
+def _fallback_registry(app: Any) -> dict[str, dict]:
+    return _FALLBACK.setdefault(id(app), {})
+
+
+def _key(path: Path) -> str:
+    try:
+        return str(path.resolve())
+    except Exception:
+        return str(path)
+
+
+def _hash_bytes(data: bytes) -> str:
+    return hashlib.sha256(data).hexdigest()
+
+
+def _file_meta(path: Path) -> tuple[float, int, str | None]:
+    st = path.stat()
+    sha: str | None = None
+    if st.st_size <= _MAX_HASH_BYTES:
+        try:
+            sha = _hash_bytes(path.read_bytes())
+        except OSError:
+            sha = None
+    return st.st_mtime, st.st_size, sha
+
+
+def record_read(app: Any, path: Path, *, full: bool) -> None:
+    """Record that `path` was read this session.
+
+    `full` must be False for a partial read (offset/limit or a truncated
+    large-file view) — a partial read must NOT satisfy the guard.
+    """
+    try:
+        mtime, size, sha = _file_meta(path)
+    except OSError:
+        return
+    _registry(app)[_key(path)] = {
+        "mtime": mtime,
+        "size": size,
+        "sha": sha,
+        "full": bool(full),
+    }
+
+
+def record_write(app: Any, path: Path, content: str) -> None:
+    """Refresh read-state after a successful write/edit (claude-code write-back)
+    so the model's own writes never trip the guard next round."""
+    try:
+        mtime, size, _ = _file_meta(path)
+    except OSError:
+        mtime, size = 0.0, len(content.encode("utf-8", "replace"))
+    _registry(app)[_key(path)] = {
+        "mtime": mtime,
+        "size": size,
+        "sha": _hash_bytes(content.encode("utf-8", "replace")),
+        "full": True,
+    }
+
+
+def is_armed(app: Any) -> bool:
+    """True once the session has ≥1 read on record. The guard only enforces
+    when armed (see module docstring)."""
+    reg = getattr(app, _ATTR, None)
+    if isinstance(reg, dict) and reg:
+        return True
+    return bool(_FALLBACK.get(id(app)))
+
+
+def check(app: Any, path: Path) -> str | None:
+    """Return None if editing `path` is allowed, else a reason code:
+
+      * 'unread'  — never read this session
+      * 'partial' — only a partial (offset/limit/truncated) read on record
+      * 'stale'   — file changed on disk since it was read
+
+    Only meaningful when `is_armed(app)` is True.
+    """
+    entry = _registry(app).get(_key(path))
+    if entry is None:
+        return "unread"
+    if not entry.get("full"):
+        return "partial"
+    try:
+        st = path.stat()
+    except OSError:
+        # File vanished — let the tool's own not-found handling deal with it.
+        return None
+    # Fresh: mtime has not advanced past the recorded read.
+    if st.st_mtime <= entry["mtime"] + 1e-6:
+        return None
+    # mtime advanced — content-equality fallback (formatter / AV / cloud-sync
+    # touch that changes mtime but not the bytes). Only applies to full reads,
+    # which are the only ones with a stored hash.
+    sha = entry.get("sha")
+    if sha is not None:
+        try:
+            if _hash_bytes(path.read_bytes()) == sha:
+                # Same bytes — refresh mtime so we don't re-hash every round.
+                entry["mtime"] = st.st_mtime
+                entry["size"] = st.st_size
+                return None
+        except OSError:
+            return None
+    return "stale"
+
+
+def guard_edit(app: Any, path: Path, display_path: str) -> str | None:
+    """Read-before-edit guard for surgical edits (edit_file / multi_edit).
+
+    Returns an actionable error string to hand back to the model, or None to
+    allow the edit. No-op unless the session is armed.
+    """
+    if not is_armed(app):
+        return None
+    reason = check(app, path)
+    if reason == "unread":
+        return (
+            f"REJECTED: read {display_path} before editing it. You are editing a "
+            f"file you have not read this session, so `old_string` is being "
+            f"matched against text you have not seen. Call read_file "
+            f"path={display_path!r} first, then edit with an exact anchor."
+        )
+    if reason == "partial":
+        return (
+            f"REJECTED: you only read PART of {display_path} (offset/limit or a "
+            f"truncated view). Read the whole file — or at least the full "
+            f"region around your edit — before editing, so `old_string` "
+            f"matches the current text. Call read_file path={display_path!r}."
+        )
+    if reason == "stale":
+        return (
+            f"REJECTED: {display_path} changed on disk since you read it (an edit "
+            f"elsewhere, a formatter, or another process). Your `old_string` "
+            f"may no longer match. Re-read it (read_file path={display_path!r}) "
+            f"to get the current text, then edit again."
+        )
+    return None
+
+
+def guard_overwrite(app: Any, path: Path, display_path: str, existed: bool) -> str | None:
+    """Staleness guard for write_file overwrites.
+
+    write_file is the create-or-full-rewrite tool, so — unlike edit_file — it
+    does NOT require a prior read (a fresh scaffold/rewrite is legitimate). But
+    if the file WAS read this session and has since changed on disk, a blind
+    overwrite would clobber those changes; refuse it. Returns an error string
+    or None.
+    """
+    if not existed or not is_armed(app):
+        return None
+    if check(app, path) == "stale":
+        return (
+            f"REJECTED: {display_path} changed on disk since you last read it. "
+            f"Overwriting now would silently clobber those changes. Re-read it "
+            f"(read_file path={display_path!r}) to see the current contents, "
+            f"then rewrite intentionally."
+        )
+    return None

localcode/tools/skill_tool.py

@@ -0,0 +1,41 @@
+"""skill — model-invoked recipe loader (Voyager / agent / minimal-agent pattern)."""
+from __future__ import annotations
+
+from .base import ToolContext
+
+SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "skill",
+        "description": (
+            "Load a named recipe's instructions into the conversation. "
+            "Use when the user's request matches a skill listed under "
+            "'Available skills' in your system prompt. The skill body "
+            "returns as the tool result; your next turn should follow it."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string", "description": "Skill name, e.g. 'locate' or 'run-tests'."},
+            },
+            "required": ["name"],
+        },
+    },
+}
+
+
+def execute(ctx: ToolContext, args: dict) -> str:
+    """Load a named skill's body and return it as tool-result text. The
+    next agent turn will have the instructions in-context and should
+    act on them. Mirrors agent's SkillTool inline-context execution —
+    no sub-agent fork.
+    """
+    from ..skills import load_registry, invoke_skill
+    name = (args.get("name") or "").strip()
+    if not name:
+        return (
+            "Error: skill tool requires `name`. Check the 'Available skills' "
+            "block in your system prompt for valid names."
+        )
+    registry = load_registry(ctx.app.repo_root)
+    return invoke_skill(registry, name)