file_tools_read_tracking.py 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427
  1. """Per-task read/search bookkeeping for the file tools.
  2. Process-lifetime state behind read_file/search_files/write_file/patch.
  3. Per task_id ``_read_tracker``
  4. stores: ``last_key``/``consecutive`` (loop detection; reset by any OTHER tool
  5. call), ``read_history`` (diagnostics), ``dedup`` (key -> file metadata; survives context
  6. compression), ``dedup_generation_reads`` (keys whose full content was served since
  7. the last compaction boundary; cleared on compression so one recovery read returns
  8. full content), ``dedup_hits`` (stub-loop breaker), ``read_timestamps``
  9. (staleness warnings), ``read_coverage`` (per resolved path: the line ranges the
  10. task has paged through at one file version — contiguous pages that reach the last line
  11. count as a whole-file read), ``full_write_baselines`` (resolved paths whose
  12. whole-file content this task saw via unredacted read_file page(s) or wrote via
  13. write_file, or patched from a baseline it already held; required before write_file
  14. may overwrite an existing file), ``blind_patches`` (resolved path -> sha256 a patch
  15. of this task wrote without such a baseline, for the refusal wording) and
  16. ``not_found`` (short-TTL negative cache). Every
  17. container is hard-capped (``_cap_read_tracker_data``) so long sessions stay small.
  18. """
  19. import hashlib
  20. import logging
  21. import os
  22. import stat
  23. import threading
  24. import time
  25. from tools.file_state import _evict_oldest
  26. from tools.file_tools_paths import _authoritative_workspace_root, _resolve_path_for_task
  27. logger = logging.getLogger("tools.file_tools")
  28. _read_tracker_lock = threading.Lock()
  29. _read_tracker: dict = {}
  30. # Consecutive patch failures per (task_id, resolved_path); escalates the hint
  31. # when the model keeps failing the same file. Reset on a successful patch.
  32. _patch_failure_lock = threading.Lock()
  33. _patch_failure_tracker: dict = {} # {task_id: {resolved_path: count}}
  34. _PATCH_FAILURE_PATHS_CAP = 64
  35. # Only the most recent reads matter for dedup, loop detection and external-edit
  36. # warnings; caps bound accretion regardless of session length.
  37. _READ_HISTORY_CAP = 500
  38. _DEDUP_CAP = 1000
  39. _READ_TIMESTAMPS_CAP = 1000
  40. _FULL_WRITE_BASELINES_CAP = 1000
  41. _NOT_FOUND_CAP = 500
  42. _NOT_FOUND_TTL_SECONDS = 60.0 # a path that didn't exist may be created soon
  43. def _task_data(task_id: str) -> dict:
  44. """Get-or-create the tracker entry for *task_id*, back-filling missing containers
  45. (search_tool / tests create partial entries). Lock must be held."""
  46. task_data = _read_tracker.setdefault(task_id, {
  47. "last_key": None, "consecutive": 0, "read_history": set()})
  48. for key in ("dedup", "dedup_hits", "read_timestamps", "read_coverage", "full_write_baselines",
  49. "blind_patches"):
  50. task_data.setdefault(key, {})
  51. task_data.setdefault("dedup_generation_reads", set())
  52. return task_data
  53. def _record_patch_failure(task_id: str, resolved_path: str) -> int:
  54. """Increment and return the consecutive-failure count for this path."""
  55. with _patch_failure_lock:
  56. task_failures = _patch_failure_tracker.setdefault(task_id, {})
  57. # Evict the oldest entry once a task has failed on many distinct files.
  58. if resolved_path not in task_failures:
  59. _evict_oldest(task_failures, _PATCH_FAILURE_PATHS_CAP - 1)
  60. task_failures[resolved_path] = task_failures.get(resolved_path, 0) + 1
  61. return task_failures[resolved_path]
  62. def _reset_patch_failures(task_id: str, resolved_paths: list) -> None:
  63. """Clear consecutive-failure counts for the given paths."""
  64. if not resolved_paths:
  65. return
  66. with _patch_failure_lock:
  67. task_failures = _patch_failure_tracker.get(task_id)
  68. for rp in resolved_paths if task_failures else ():
  69. task_failures.pop(rp, None)
  70. def _cap_read_tracker_data(task_data: dict) -> None:
  71. """Enforce size caps on the per-task sub-containers. Call with ``_read_tracker_lock`` held."""
  72. # Caps are read at call time so tests can monkeypatch the module constants.
  73. for key, cap in (
  74. ("read_history", _READ_HISTORY_CAP),
  75. ("dedup", _DEDUP_CAP),
  76. ("dedup_hits", _DEDUP_CAP),
  77. ("dedup_generation_reads", _DEDUP_CAP),
  78. ("read_timestamps", _READ_TIMESTAMPS_CAP),
  79. ("read_coverage", _READ_TIMESTAMPS_CAP),
  80. ("full_write_baselines", _FULL_WRITE_BASELINES_CAP),
  81. ("blind_patches", _FULL_WRITE_BASELINES_CAP),
  82. ("not_found", _NOT_FOUND_CAP)):
  83. container = task_data.get(key)
  84. if container is not None and len(container) > cap:
  85. _evict_oldest(container, cap)
  86. def _resolved_or_none(filepath: str, task_id: str) -> str | None:
  87. try:
  88. return str(_resolve_path_for_task(filepath, task_id))
  89. except (OSError, ValueError):
  90. return None
  91. def _pop_not_found(op: str, resolved_str: str, task_id: str) -> None:
  92. """Drop the negative-cache entry for *(op, resolved_str)*. Lock must be held."""
  93. task_data = _read_tracker.get(task_id)
  94. nf = task_data.get("not_found") if task_data else None
  95. if nf:
  96. nf.pop((op, resolved_str), None)
  97. def _check_not_found_cache(op: str, resolved_str: str, task_id: str) -> str | None:
  98. """Return cached not-found JSON for *(op, resolved_str)* if still fresh.
  99. *op* is "read" or "search" (different error JSON shapes). Evicted by TTL,
  100. by write_file/patch on the path, or by any other tool call.
  101. """
  102. with _read_tracker_lock:
  103. task_data = _read_tracker.get(task_id)
  104. entry = (task_data.get("not_found") or {}).get((op, resolved_str)) if task_data else None
  105. if entry is None:
  106. return None
  107. ts, cached_json = entry
  108. if time.monotonic() - ts > _NOT_FOUND_TTL_SECONDS:
  109. _pop_not_found(op, resolved_str, task_id)
  110. return None
  111. # "check → create → read" is common, so never serve a stale miss for a path
  112. # that now exists. The stat runs OUTSIDE the tracker lock: a hung stat on a
  113. # dead network mount must not stall every task.
  114. if os.path.exists(resolved_str):
  115. with _read_tracker_lock:
  116. _pop_not_found(op, resolved_str, task_id)
  117. return None
  118. return cached_json
  119. def _record_not_found(op: str, resolved_str: str, task_id: str, error_json: str) -> None:
  120. """Cache a not-found error so the next *op* call for *resolved_str* skips I/O."""
  121. with _read_tracker_lock:
  122. task_data = _task_data(task_id)
  123. task_data.setdefault("not_found", {})[(op, resolved_str)] = (time.monotonic(), error_json)
  124. _cap_read_tracker_data(task_data)
  125. def _bump_consecutive(task_data: dict, key: tuple) -> int:
  126. """Update last_key/consecutive for *key* and return the new count. Lock must be held."""
  127. if task_data["last_key"] == key:
  128. task_data["consecutive"] += 1
  129. else:
  130. task_data["last_key"] = key
  131. task_data["consecutive"] = 1
  132. return task_data["consecutive"]
  133. def reset_file_dedup(task_id: str | None = None):
  134. """Advance the read-dedup generation after context compression (one task, or all
  135. when ``task_id`` is None). The per-key ``dedup`` metadata map is PRESERVED so unchanged
  136. files keep returning stubs instead of re-bloating the reclaimed context; the
  137. generation-read set is cleared so the FIRST unchanged read of each key after
  138. compaction returns full content the summary may have dropped. Stub-hit counters
  139. are cleared so the hard block restarts fresh. write_file baselines survive
  140. exactly like the dedup map does — while the file metadata still matches the
  141. stamp this task recorded; byte identity is checked before overwriting. A baseline
  142. whose file changed underneath is dropped
  143. (the stat runs outside the lock so a hung mount cannot stall other tasks)."""
  144. with _read_tracker_lock:
  145. if task_id:
  146. targets = [_read_tracker[task_id]] if _read_tracker.get(task_id) else []
  147. else:
  148. targets = list(_read_tracker.values())
  149. for task_data in targets:
  150. if "dedup_hits" in task_data:
  151. task_data["dedup_hits"].clear()
  152. task_data.setdefault("dedup_generation_reads", set()).clear()
  153. candidates = [(task_data, dict(task_data.get("full_write_baselines", {})))
  154. for task_data in targets]
  155. for task_data, baselines in candidates:
  156. changed = {p for p, version in baselines.items() if _file_metadata(p) != version[:-1]}
  157. if changed:
  158. with _read_tracker_lock:
  159. for p in changed:
  160. if task_data["full_write_baselines"].get(p) == baselines[p]:
  161. task_data["full_write_baselines"].pop(p, None)
  162. def notify_other_tool_call(task_id: str = "default"):
  163. """Reset the consecutive read/search counter for a task.
  164. Called by the dispatcher for every tool OTHER than read_file/search_files.
  165. Also clears stub-hit counters and the not-found cache: any other tool may
  166. have created a previously-missing path (or flipped its permissions).
  167. """
  168. with _read_tracker_lock:
  169. task_data = _read_tracker.get(task_id)
  170. if task_data:
  171. task_data["last_key"] = None
  172. task_data["consecutive"] = 0
  173. for key in ("dedup_hits", "not_found"):
  174. if task_data.get(key):
  175. task_data[key].clear()
  176. def _invalidate_dedup_for_path(filepath: str, task_id: str) -> None:
  177. """Evict every dedup entry (all offset/limit ranges) and not-found entry for *filepath*
  178. after a write, so the next read returns fresh content. Acquires the lock itself."""
  179. resolved = _resolved_or_none(filepath, task_id)
  180. if resolved is None:
  181. return
  182. with _read_tracker_lock:
  183. task_data = _read_tracker.get(task_id)
  184. if task_data is None:
  185. return
  186. dedup = task_data.get("dedup")
  187. if dedup:
  188. for k in [k for k in dedup if k[0] == resolved]:
  189. del dedup[k]
  190. _pop_not_found("read", resolved, task_id)
  191. _pop_not_found("search", resolved, task_id)
  192. def _update_read_timestamp(filepath: str, task_id: str) -> None:
  193. """After a successful write: invalidate dedup and refresh the stored mtime so
  194. consecutive edits by the same task don't trigger false staleness warnings.
  195. Also invalidates the dedup cache for the written path so that subsequent reads return fresh content
  196. (fixes #13144).
  197. """
  198. _invalidate_dedup_for_path(filepath, task_id)
  199. resolved = _resolved_or_none(filepath, task_id)
  200. if resolved is None:
  201. return
  202. try:
  203. current_mtime = os.path.getmtime(resolved)
  204. except OSError:
  205. return
  206. with _read_tracker_lock:
  207. task_data = _read_tracker.get(task_id)
  208. if task_data is not None:
  209. task_data.setdefault("read_timestamps", {})[resolved] = current_mtime
  210. _cap_read_tracker_data(task_data)
  211. def _file_metadata(resolved: str) -> tuple | None:
  212. try:
  213. st = os.stat(resolved)
  214. return st.st_dev, st.st_ino, st.st_size, st.st_mtime_ns, st.st_ctime_ns
  215. except OSError:
  216. return None
  217. def _file_version(resolved: str) -> tuple | None:
  218. """A byte snapshot, not just mtime (editors/copy tools can preserve that)."""
  219. try:
  220. if not stat.S_ISREG(os.stat(resolved).st_mode):
  221. return None
  222. fd = os.open(resolved, os.O_RDONLY | getattr(os, "O_NONBLOCK", 0) | getattr(os, "O_BINARY", 0))
  223. with os.fdopen(fd, "rb") as stream:
  224. before = os.fstat(stream.fileno())
  225. if not stat.S_ISREG(before.st_mode):
  226. return None
  227. digest = hashlib.file_digest(stream, "sha256").digest()
  228. after = os.stat(resolved)
  229. fields = ("st_dev", "st_ino", "st_size", "st_mtime_ns", "st_ctime_ns")
  230. version = tuple(getattr(before, name) for name in fields)
  231. if version == tuple(getattr(after, name) for name in fields):
  232. return (*version, digest)
  233. return None
  234. except OSError:
  235. return None
  236. def _mark_full_write_baseline(resolved: str, task_id: str, expected_sha256: str | None = None) -> None:
  237. """Record that *task_id* saw the whole current content of *resolved* (full
  238. unredacted read_file, or its own successful write_file), so a later
  239. write_file may replace the file. Acquires the lock itself."""
  240. version = _file_version(resolved)
  241. if version is None or (expected_sha256 is not None and version[-1].hex() != expected_sha256):
  242. return
  243. with _read_tracker_lock:
  244. task_data = _task_data(task_id)
  245. task_data["full_write_baselines"][str(resolved)] = version
  246. task_data["blind_patches"].pop(str(resolved), None)
  247. _cap_read_tracker_data(task_data)
  248. def _has_full_write_baseline(resolved: str, task_id: str) -> bool:
  249. with _read_tracker_lock:
  250. task_data = _read_tracker.get(task_id) or {}
  251. baseline = task_data.get("full_write_baselines", {}).get(str(resolved))
  252. return baseline is not None and _file_version(resolved) == baseline
  253. def _known_full_content_sha256(resolved_paths, task_id: str) -> dict:
  254. """``{resolved: sha256 hex}`` for each path whose recorded full-write baseline still
  255. matches the bytes on disk. Call under the per-path locks, before a patch reads."""
  256. with _read_tracker_lock:
  257. baselines = dict((_read_tracker.get(task_id) or {}).get("full_write_baselines", {}))
  258. known = {}
  259. for resolved in {str(r) for r in resolved_paths if r}:
  260. baseline = baselines.get(resolved)
  261. if baseline is not None and _file_version(resolved) == baseline:
  262. known[resolved] = baseline[-1].hex()
  263. return known
  264. def _carry_full_write_baselines(task_id: str, known: dict, writes, path_to_resolved: dict) -> None:
  265. """After this task's own successful patch: keep the whole-file baseline of each written
  266. path when the task knew the exact bytes the patch read (``known``, from
  267. ``_known_full_content_sha256``) or the patch created the file (read sha ``""``). Then
  268. the task knows every byte it wrote. ``writes`` is ``PatchResult._writes`` in order, so
  269. a second edit of the same path chains from the first. The mark re-hashes the disk and
  270. requires the bytes the patch wrote, so a writer landing after the patch leaves no
  271. baseline. A write the task could not vouch for is noted in ``blind_patches``."""
  272. lookup = {raw: r for raw, r in path_to_resolved.items() if r}
  273. lookup.update({r: r for r in lookup.values()})
  274. known = dict(known)
  275. written: dict = {}
  276. for path, read_sha, written_sha in writes:
  277. resolved = lookup.get(path)
  278. if resolved is None:
  279. continue # a backend-side path (sandbox, translated mount): no host baseline
  280. vouched = read_sha == "" or (read_sha is not None and read_sha == known.get(resolved))
  281. known[resolved] = written_sha if vouched else None
  282. written[resolved] = written_sha
  283. for resolved, written_sha in written.items():
  284. if written_sha is None:
  285. continue
  286. if known[resolved] is not None:
  287. _mark_full_write_baseline(resolved, task_id, written_sha)
  288. continue
  289. with _read_tracker_lock:
  290. task_data = _task_data(task_id)
  291. task_data["blind_patches"][resolved] = written_sha
  292. _cap_read_tracker_data(task_data)
  293. def _is_own_blind_patch(resolved: str, task_id: str) -> bool:
  294. """True when the bytes on disk are exactly what this task's own patch wrote without a
  295. full-content baseline (a blind patch, or one after a partial view)."""
  296. with _read_tracker_lock:
  297. written_sha = ((_read_tracker.get(task_id) or {}).get("blind_patches") or {}).get(str(resolved))
  298. if written_sha is None:
  299. return False
  300. version = _file_version(resolved)
  301. return version is not None and version[-1].hex() == written_sha
  302. _READ_COVERAGE_RANGES_CAP = 256
  303. def _note_read_coverage(task_data: dict, resolved: str, version: tuple, start: int, end: int,
  304. total_lines, redacted: bool) -> tuple[bool, bool]:
  305. """Merge the page ``start..end`` into this task's coverage of *resolved* and return
  306. ``(complete, redacted_any)``: whether pages taken at this same *version* now reach from
  307. line 1 to *total_lines*, and whether any of them came back redacted. A file too large
  308. for one read_file page (>2000 lines / the char budget) can only ever be seen this
  309. way, so paging through it must count as a whole-file read. A new version restarts the
  310. coverage (the earlier pages describe a file that no longer exists). Lock must be held."""
  311. coverage = task_data.setdefault("read_coverage", {})
  312. entry = coverage.get(resolved)
  313. if entry is None or entry["version"] != version or len(entry["ranges"]) > _READ_COVERAGE_RANGES_CAP:
  314. entry = coverage[resolved] = {"version": version, "ranges": [], "redacted": False}
  315. entry["redacted"] = entry["redacted"] or redacted
  316. merged: list[tuple[int, int]] = []
  317. for s, e in sorted(entry["ranges"] + [(start, end)]):
  318. if merged and s <= merged[-1][1] + 1:
  319. merged[-1] = (merged[-1][0], max(merged[-1][1], e))
  320. else:
  321. merged.append((s, e))
  322. entry["ranges"] = merged
  323. complete = (isinstance(total_lines, int) and total_lines > 0
  324. and merged[0][0] <= 1 and merged[0][1] >= total_lines)
  325. return complete, entry["redacted"]
  326. def _read_mtime_drifted(filepath: str, task_id: str) -> bool:
  327. """True when the file's mtime changed since this task last read it. False when
  328. never read, fresh, or unstattable (a deleted file is the write's problem)."""
  329. resolved = _resolved_or_none(filepath, task_id)
  330. if resolved is None:
  331. return False
  332. with _read_tracker_lock:
  333. task_data = _read_tracker.get(task_id)
  334. read_mtime = task_data.get("read_timestamps", {}).get(resolved) if task_data else None
  335. if read_mtime is None:
  336. return False
  337. try:
  338. return os.path.getmtime(resolved) != read_mtime
  339. except OSError:
  340. return False
  341. def _check_file_staleness(filepath: str, task_id: str) -> str | None:
  342. """Warn (don't block) when the file's mtime changed since this task last read it."""
  343. if _read_mtime_drifted(filepath, task_id):
  344. return (
  345. f"Warning: {filepath} was modified since you last read it "
  346. "(external edit or concurrent agent). The content you read may be "
  347. "stale. Consider re-reading the file to verify before writing.")
  348. return None
  349. def _mark_verification_stale(task_id: str, resolved_paths: list[str],
  350. session_id: str | None = None) -> None:
  351. """Best-effort note that successful edits made prior verification stale. cwd: the
  352. first edited path's recognised project root, else the workspace root, else the first parent."""
  353. from pathlib import Path
  354. paths = [p for p in resolved_paths if p]
  355. if not paths:
  356. return
  357. try:
  358. from agent.coding_context import project_facts_for
  359. from agent.verification_evidence import mark_workspace_edited
  360. parents = [str(Path(p).parent) for p in paths]
  361. cwd = (next((c for c in parents if project_facts_for(c)), None)
  362. or _authoritative_workspace_root(task_id) or parents[0])
  363. mark_workspace_edited(session_id=session_id or task_id, cwd=cwd, paths=paths)
  364. except Exception:
  365. logger.debug("verification stale marker failed", exc_info=True)