file_state.py 10 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261
  1. """Cross-agent file state coordination.
  2. Prevents mangled edits when concurrent subagents (same process, same
  3. filesystem) touch the same file: B writes a file A already read, so A's next
  4. write would clobber B's changes. Complements the single-agent path-overlap
  5. check in ``agent.tool_dispatch_helpers._should_parallelize_tool_batch``. A process-wide
  6. ``FileStateRegistry`` tracks per-agent read stamps, the global last writer and
  7. a per-path lock; every method is a no-op under ``HERMES_DISABLE_FILE_STATE_GUARD=1``.
  8. """
  9. from __future__ import annotations
  10. import os
  11. import threading
  12. import time
  13. from collections import defaultdict
  14. from contextlib import contextmanager
  15. from pathlib import Path
  16. from typing import Dict, Iterable, List, Optional, Tuple
  17. # (mtime, read_ts, partial). partial=True when read_file returned a windowed
  18. # view (offset > 1 or limit < total_lines) — a later write should still warn
  19. # so the model re-reads in full.
  20. ReadStamp = tuple[float, float, bool]
  21. # Bounded so long sessions don't accumulate unbounded state.
  22. _MAX_PATHS_PER_AGENT = 4096
  23. _MAX_GLOBAL_WRITERS = 4096
  24. def _disabled() -> bool:
  25. # Re-read each call so tests can toggle via monkeypatch.setenv.
  26. return os.environ.get("HERMES_DISABLE_FILE_STATE_GUARD", "").strip() == "1"
  27. def guard_disabled() -> bool:
  28. """True when the user switched the read-before-write guard off; the file
  29. tools then warn instead of refusing stale/unread write_file overwrites."""
  30. return _disabled()
  31. def _mtime_or_none(resolved: str) -> Optional[float]:
  32. try:
  33. return os.path.getmtime(resolved)
  34. except OSError:
  35. return None
  36. def _fmt_ts(ts: float) -> str:
  37. # Short wall-clock for warnings; avoids datetime formatting on the hot path.
  38. return time.strftime("%H:%M:%S", time.localtime(ts))
  39. def _evict_oldest(container, cap: int) -> None:
  40. """Pop entries until *container* is within *cap* (sets: arbitrary; dicts: oldest
  41. by insertion order). An eviction only costs one redundant re-send or staleness check."""
  42. for _ in range(len(container) - cap):
  43. try:
  44. if isinstance(container, set):
  45. container.pop()
  46. else:
  47. container.pop(next(iter(container)))
  48. except (StopIteration, KeyError):
  49. break
  50. class FileStateRegistry:
  51. """Process-wide coordinator for cross-agent file edits."""
  52. def __init__(self) -> None:
  53. self._reads: dict[str, dict[str, ReadStamp]] = defaultdict(dict)
  54. self._last_writer: dict[str, tuple[str, float]] = {}
  55. self._path_locks: dict[str, threading.Lock] = {}
  56. self._path_lock_users: dict[str, int] = {}
  57. self._meta_lock = threading.Lock() # guards _path_locks
  58. self._state_lock = threading.Lock() # guards _reads + _last_writer
  59. @contextmanager
  60. def lock_path(self, resolved: str):
  61. """Per-path lock: threads on the same path serialize, different paths proceed.
  62. The lock entry is dropped once the last holder/waiter exits."""
  63. with self._meta_lock:
  64. lock = self._path_locks.setdefault(resolved, threading.Lock())
  65. self._path_lock_users[resolved] = self._path_lock_users.get(resolved, 0) + 1
  66. lock.acquire()
  67. try:
  68. yield
  69. finally:
  70. lock.release()
  71. with self._meta_lock:
  72. users = self._path_lock_users[resolved] - 1
  73. if users:
  74. self._path_lock_users[resolved] = users
  75. else:
  76. self._path_lock_users.pop(resolved, None)
  77. self._path_locks.pop(resolved, None)
  78. def _stamp(self, task_id: str, resolved: str, mtime: float, now: float, partial: bool) -> None:
  79. """Caller holds ``_state_lock``."""
  80. agent_reads = self._reads[task_id]
  81. agent_reads[resolved] = (float(mtime), now, bool(partial))
  82. _evict_oldest(agent_reads, _MAX_PATHS_PER_AGENT)
  83. def record_read(self, task_id: str, resolved: str, *, partial: bool = False,
  84. mtime: Optional[float] = None) -> None:
  85. if _disabled():
  86. return
  87. mtime = _mtime_or_none(resolved) if mtime is None else mtime
  88. if mtime is None:
  89. return
  90. with self._state_lock:
  91. self._stamp(task_id, resolved, mtime, time.time(), partial)
  92. def note_write(self, task_id: str, resolved: str, *, mtime: Optional[float] = None) -> None:
  93. """Record a successful write: global last-writer AND this agent's own
  94. read stamp (a write is an implicit read of the current content)."""
  95. if _disabled():
  96. return
  97. mtime = _mtime_or_none(resolved) if mtime is None else mtime
  98. if mtime is None:
  99. return
  100. now = time.time()
  101. with self._state_lock:
  102. self._last_writer[resolved] = (task_id, now)
  103. _evict_oldest(self._last_writer, _MAX_GLOBAL_WRITERS)
  104. self._stamp(task_id, resolved, mtime, now, False)
  105. def check_stale(self, task_id: str, resolved: str) -> Optional[str]:
  106. """Model-facing warning if this write would be stale, else ``None``. Severity
  107. order: sibling wrote after our read > mtime drift / partial read > never read."""
  108. if _disabled():
  109. return None
  110. with self._state_lock:
  111. stamp = self._reads.get(task_id, {}).get(resolved)
  112. last_writer = self._last_writer.get(resolved)
  113. if stamp is None and last_writer is None: # net-new file / first touch
  114. return None
  115. current_mtime = _mtime_or_none(resolved)
  116. if current_mtime is None:
  117. return None # file doesn't exist — write creates it; not stale
  118. if last_writer is not None:
  119. writer_tid, writer_ts = last_writer
  120. if writer_tid != task_id:
  121. if stamp is None:
  122. return (
  123. f"{resolved} was modified by sibling subagent "
  124. f"{writer_tid!r} but this agent never read it. "
  125. "Read the file before writing to avoid overwriting "
  126. "the sibling's changes.")
  127. read_ts = stamp[1]
  128. if writer_ts > read_ts:
  129. return (
  130. f"{resolved} was modified by sibling subagent "
  131. f"{writer_tid!r} at {_fmt_ts(writer_ts)} — after "
  132. f"this agent's last read at {_fmt_ts(read_ts)}. "
  133. "Re-read the file before writing.")
  134. if stamp is not None:
  135. read_mtime, _read_ts, partial = stamp
  136. if current_mtime != read_mtime:
  137. return (
  138. f"{resolved} was modified since you last read it "
  139. "on disk (external edit or unrecorded writer). "
  140. "Re-read the file before writing.")
  141. if partial:
  142. return (
  143. f"{resolved} was last read with offset/limit pagination "
  144. "(partial view). Read the remaining pages, or use patch, "
  145. "before overwriting it.")
  146. return None
  147. return (
  148. f"{resolved} was not read by this agent. "
  149. "Read the file first so you can write an informed edit.")
  150. def writes_since(self, exclude_task_id: str, since_ts: float,
  151. paths: Iterable[str]) -> dict[str, list[str]]:
  152. """``{writer_task_id: [paths]}`` for writes after ``since_ts`` by agents
  153. other than ``exclude_task_id`` (delegate_task's "subagent modified files
  154. you previously read" reminder)."""
  155. if _disabled():
  156. return {}
  157. paths_set = set(paths)
  158. out: dict[str, list[str]] = defaultdict(list)
  159. with self._state_lock:
  160. for p, (writer_tid, ts) in self._last_writer.items():
  161. if writer_tid != exclude_task_id and ts >= since_ts and p in paths_set:
  162. out[writer_tid].append(p)
  163. return dict(out)
  164. def known_reads(self, task_id: str) -> list[str]:
  165. """Resolved paths this agent has read."""
  166. if _disabled():
  167. return []
  168. with self._state_lock:
  169. return list(self._reads.get(task_id, {}).keys())
  170. def forget_task(self, task_id: str) -> None:
  171. """Release read stamps and writer claims owned by a task after its lifecycle ends.
  172. A finished task is not a concurrent sibling: leaving its writer claims behind makes
  173. the next run of the same job (a fresh ``cron:<job>:<uuid>`` id) refuse to write the
  174. same scratch path as "modified by sibling subagent" hours after the writer exited."""
  175. with self._state_lock:
  176. self._reads.pop(task_id, None)
  177. for p in [p for p, (writer_tid, _ts) in self._last_writer.items() if writer_tid == task_id]:
  178. del self._last_writer[p]
  179. def clear(self) -> None:
  180. """Reset all state. Intended for tests only."""
  181. with self._state_lock:
  182. self._reads.clear()
  183. self._last_writer.clear()
  184. with self._meta_lock:
  185. self._path_locks.clear()
  186. self._path_lock_users.clear()
  187. _registry = FileStateRegistry()
  188. def get_registry() -> FileStateRegistry:
  189. return _registry
  190. # Convenience wrappers (short names used at call sites).
  191. def record_read(task_id: str, resolved_or_path: str | Path, *, partial: bool = False) -> None:
  192. _registry.record_read(task_id, str(resolved_or_path), partial=partial)
  193. def note_write(task_id: str, resolved_or_path: str | Path) -> None:
  194. _registry.note_write(task_id, str(resolved_or_path))
  195. def check_stale(task_id: str, resolved_or_path: str | Path) -> Optional[str]:
  196. return _registry.check_stale(task_id, str(resolved_or_path))
  197. def lock_path(resolved_or_path: str | Path):
  198. return _registry.lock_path(str(resolved_or_path))
  199. def writes_since(exclude_task_id: str, since_ts: float, paths: Iterable[str | Path]) -> dict[str, list[str]]:
  200. return _registry.writes_since(exclude_task_id, since_ts, [str(p) for p in paths])
  201. def known_reads(task_id: str) -> list[str]:
  202. return _registry.known_reads(task_id)
  203. __all__ = [
  204. "FileStateRegistry",
  205. "check_stale",
  206. "get_registry",
  207. "known_reads",
  208. "lock_path",
  209. "note_write",
  210. "record_read",
  211. "writes_since",
  212. ]