iA0dZddlmZddlZddlZddlZddlmZddlm Z ddl m Z ddl m Z mZmZmZmZeeeefZdZdZGd d ZeZd-d Zd.dZd/dZd0dZddd1dZd2d Zd3d"Zd4d#Z d5d)Z!d6d+Z"gd,Z#dS)7uCross-agent file state coordination. Prevents mangled edits when concurrent subagents (same process, same filesystem) touch the same file. Complements the single-agent path-overlap check in ``run_agent._should_parallelize_tool_batch`` — this module catches the case where subagent B writes a file that subagent A already read, so A's next write would overwrite B's changes with stale content. Design ------ A process-wide singleton ``FileStateRegistry`` tracks, per resolved path: * per-agent read stamps: {task_id: {path: (mtime, read_ts, partial)}} * last writer globally: {path: (task_id, write_ts)} * per-path ``threading.Lock`` for read→modify→write critical sections Three public hooks are used by the file tools: * ``record_read(task_id, path, *, partial)`` — called by read_file * ``note_write(task_id, path)`` — called after write_file / patch * ``check_stale(task_id, path)`` — called BEFORE write_file / patch Plus ``lock_path(path)`` — a context-manager returning a per-path lock to wrap the whole read→modify→write block. And ``writes_since(task_id, since_ts, paths)`` for the subagent-completion reminder in delegate_tool. All methods are no-ops when ``HERMES_DISABLE_FILE_STATE_GUARD=1`` is set. This module is intentionally separate from ``_read_tracker`` in ``file_tools.py`` — that tracker is per-task and handles consecutive-read loop detection, which is a different concern. ) annotationsN) defaultdict)contextmanager)Path)DictIterableListOptionalTupleicxeZdZdZd!dZd"dZed#d Zd d d d$dZd dd%dZ d&dZ d'dZ d(dZ d!d Z d S))FileStateRegistryz4Process-wide coordinator for cross-agent file edits.returnNonectt|_i|_i|_t j|_t j|_dSN) rdict_reads _last_writer _path_locks threadingLock _meta_lock _state_lockselfs 5/home/ubuntu/.hermes/hermes-agent/tools/file_state.py__init__zFileStateRegistry.__init__>sF7B47H7H :<68#.**$>++resolvedstrthreading.Lockc|j5|j|}|tj}||j|<|cdddS#1swxYwYdSr)rrgetrrrrlocks r _lock_forzFileStateRegistry._lock_forFs _  #''11D| ~''-1 *                   s;AAAc#K||}| dV|dS#|wxYw)uAcquire the per-path lock for a read→modify→write section. Same process, same filesystem — threads on the same path serialize. Different paths proceed in parallel. N)r&acquirereleaser$s r lock_pathzFileStateRegistry.lock_pathNsW~~h''   EEE LLNNNNNDLLNNNNs AAFN)partialmtimetask_idr+boolr,Optional[float]c|trdS|2 tj|}n#t$rYdSwxYwt j}|j5|j|}t||t|f||<t|tddddS#1swxYwYdSr) _disabledospathgetmtimeOSErrortimerrfloatr. _cap_dict_MAX_PATHS_PER_AGENT)rr-rr+r,now agent_readss r record_readzFileStateRegistry.record_read]s  ;;  F = ((22    ikk   9 9+g.K%*5\\3W $FK ! k#7 8 8 8 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9 9s"4 AAAB11B58B5)r,ctrdS|2 tj|}n#t$rYdSwxYwt j}|j5||f|j|<t|jtt||df|j ||<t|j |tddddS#1swxYwYdS)uRecord a successful write. Updates the global last-writer map AND this agent's own read stamp (a write is an implicit read — the agent now knows the current content). NF) r1r2r3r4r5r6rrr8_MAX_GLOBAL_WRITERSr7rr9)rr-rr,r:s r note_writezFileStateRegistry.note_writers? ;;  F = ((22    ikk   B B+2C.D h ' d')< = = =.3EllC-GDK  * dk'*,@ A A A  B B B B B B B B B B B B B B B B B Bs"4 AAA'CCC Optional[str]c @trdS|j5|j|i|}|j|}dddn #1swxYwY||dS t j|}n#t$rYdSwxYw|K|\}}||kr@||d|dS|d}||kr(|d|dt|dt|dS||\} } } || kr|dS| r|d S||d SdS) uReturn a model-facing warning if this write would be stale. Three staleness classes, in order of severity: 1. Sibling subagent wrote this file after this agent's last read. 2. External/unknown change (mtime differs from our last read). 3. Agent never read the file (write-without-read). Returns ``None`` when the write is safe. Does not raise — callers decide whether to block or warn. Nz" was modified by sibling subagent zg but this agent never read it. Read the file before writing to avoid overwriting the sibling's changes.z at u% — after this agent's last read at z". Re-read the file before writing.zs was modified since you last read it on disk (external edit or unrecorded writer). Re-read the file before writing.zi was last read with offset/limit pagination (partial view). Re-read the whole file before overwriting it.zS was not read by this agent. Read the file first so you can write an informed edit.) r1rrr#rr2r3r4r5_fmt_ts) rr-rstamp last_writer current_mtime writer_tid writer_tsread_ts read_mtime_read_tsr+s r check_stalezFileStateRegistry.check_stales$ ;; 4   : :KOOGR0044X>>E+//99K : : : : : : : : : : : : : : : =[04 G,,X66MM   44   "$/ !J W$$=#11%111  (w&&#;;%;;-4Y-?-?;;5'>'@'@ . .##J00== >> O**1---  . . . . . . . . . . . . . . . .CyysABBB List[str]ctrgS|j5t|j|icdddS#1swxYwYdS)z6Return the list of resolved paths this agent has read.N)r1rrTrr#keys)rr-s r known_readszFileStateRegistry.known_readss ;; I   = = 4499;;<< = = = = = = = = = = = = = = = = = =s:AA#&A#c|j5|j|jdddn #1swxYwY|j5|jddddS#1swxYwYdS)z*Reset all state. Intended for tests only.N)rrclearrrrrs rrazFileStateRegistry.clears    & & K        # # % % % & & & & & & & & & & & & & & &_ % %   " " $ $ $ % % % % % % % % % % % % % % % % % %s#3AA A BBB)rr)rr rr!)rr ) r-r rr r+r.r,r/rr)r-r rr r,r/rr)r-r rr rr@)rMr rNr7rOrPrrQr-r rr\)__name__ __module__ __qualname____doc__rr&rr*r<r?rLr[r_rarrr r ;s>>,,,,   ^ &!% 9999994"& BBBBBB8IIIIX4====%%%%%%rr rctSr) _registryrgrr get_registryrj s rr.cntjdddkS)NHERMES_DISABLE_FILE_STATE_GUARD1)r2environr#striprgrrr1r1 s* :>>;R @ @ F F H HC OOrrZr7r cPtjdtj|S)Nz%H:%M:%S)r6strftime localtime)rZs rrCrCs  =T^B%7%7 8 88rdrlimitintrct||z }|dkrdSt|}t|D]>} |t |&#t t f$rYdSwxYwdS)zDTrim a dict to ``limit`` entries by dropping insertion-order oldest.rN)leniterrangepopnext StopIterationKeyError)rtruoverit_s rr8r8s q66E>D qyy aB 4[[  EE$r((OOOOx(    EEE s"AA54A5Fr+r-resolved_or_path str | Pathr+cZt|t||dS)Nr)rir<r )r-rr+s rr<r<'s, '3'7#8#8'JJJJJrcVt|t|dSr)rir?r r-rs rr?r?+s' #&6"7"788888rr@cRt|t|Sr)rirLr rs rrLrL/s!  #.>*?*? @ @@rcPtt|Sr)rir*r )rs rr*r*3s   s#344 5 55rrMrNrOIterable[str | Path]rQcNt||d|DS)Nc,g|]}t|Srg)r ).0rYs r z writes_since..<s=T=T=Tc!ff=T=T=Tr)rir[)rMrNrOs rr[r[7s+  ! !/8=T=Te=T=T=T U UUrr\c6t|Sr)rir_)r-s rr_r_?s   ) ))r)r rjr<r?rLr*r[r_)rr )rr.)rZr7rr )rtrrurvrr)r-r rrr+r.rr)r-r rrrr)r-r rrrr@)rr)rMr rNr7rOrrrQrb)$rf __future__rr2rr6 collectionsr contextlibrpathlibrtypingrrr r r r7r. ReadStampr9r>r rirjr1rCr8r<r?rLr*r[r___all__rgrrrs@#"""""  ######%%%%%%88888888888888 %$ % G%G%G%G%G%G%G%G%V     PPPP 9999    PUKKKKKK9999AAAA6666VVVV****   r