KiUdZddlZddlZddlZddlZddlZddlmZddlm Z ddl m Z ej e ZejejejhZdZdaedzed<defd Zd Zehd Zd edefd ZdZddhZd ededzfdZ de!defdZ"ej#Z$iZ%e&ed<ej#Z'iZ(e&ed<drdede fdZ)dsdefdZ*dtdededededef dZ+drdede,fd Z-dsdefd!Z.dsdefd"Z/drdefd#Z0d ededdfd$Z1d edededzfd%Z2drded&ededefd'Z3 dud*eded+ed,ed-ed.ededefd/Z4 dvd2ed3eded4ededed5ed6ededefd7Z5d8e+d9d:e3d9d.e4d9d;e5d9gZ6d<Z7dd=l8m9Z9d>Z:d8d?d@dAdBdCdDdEdddFdDdGddHdIdJdgdKdLZ;d:dMd@dAdNdCdAdOdCdPdd&gdKdLZdhZ?diZ@djZAdkZBe9jCd8dle;e?e:dmne9jCd:dleeBe:dqndS)wz6File Tools Module - LLM agent file manipulation tools.N)Path)ShellFileOperations)redact_sensitive_texti_max_read_chars_cachedreturncttS ddlm}|}|d}t |t t fr|dkrt |atSn#t$rYnwxYwtatS)zReturn the configured max characters per file read. Reads ``file_read_max_chars`` from config.yaml on first call, caches the result for the lifetime of the process. Falls back to the built-in default if the config is missing or invalid. Nr) load_configfile_read_max_chars) rhermes_cli.configr get isinstanceintfloat Exception_DEFAULT_MAX_READ_CHARS)r cfgvals -/home/ubuntu/hermes-agent/tools/file_tools.py_get_max_read_charsrs)%% 111111kmmgg+,, cC< ( ( *S1WW%(XX ") )      4 !!sAA.. A;:A;i> /dev/tty /dev/fd/0 /dev/fd/1 /dev/fd/2 /dev/full /dev/zero /dev/stdin /dev/random /dev/stderr /dev/stdout /dev/console /dev/urandomfilepathctj|}|tvrdS|dr|drdSdS)uGReturn True if the path would hang the process (infinite output or blocking input). Uses the *literal* path — no symlink resolution — because the model specifies paths directly and realpath follows symlinks all the way through (e.g. /dev/stdin → /proc/self/fd/0 → /dev/pts/0), defeating the check. Tz/proc/)z/fd/0z/fd/1z/fd/2F)ospath expanduser_BLOCKED_DEVICE_PATHS startswithendswith)r" normalizeds r_is_blocked_devicer+Isf##H--J***tX&&:+>+>#,,t 5)z/etc/z/boot/z/usr/lib/systemd/z/var/run/docker.sockz/run/docker.sockc  tjtj|}n#tt f$r|}YnwxYwt D]}||rd|dcS |tvrd|dSdS)zHReturn an error message if the path targets a sensitive system location.z,Refusing to write to sensitive system path: zD Use the terminal tool with sudo if you need to modify system files.N) r$r%realpathr&OSError ValueError_SENSITIVE_PATH_PREFIXESr(_SENSITIVE_EXACT_PATHS)r"resolvedprefixs r_check_sensitive_pathr5bs7##BG$6$6x$@$@AA Z *   v & & VxVVV     ))) R8 R R R  4sYW$$! m44M}8MY&&! o66Q&:Q--&&7&-C KKDhPWXZYZXZP[ \ \ \# HHH%+ZZ%C%C(. 3Et(L(L&,jj1A5&I&I,2JJ7Mt,T,T&,jj1A2&F&F $$ J5  "JJz266"JJz266"JJz266!::i44"(**-=u"E"E   L7"" &**-?"G"G  /.!y)%!1)J//   L 6 60<$W-*.))++w' 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6 " ! # # # KK:Hgbqbk R R RSISISISISISISISISISISISISISISISX#<00H ,,#+ ,,,,,,,,,,,,,,, OsAA A CCB/# C/B3 3C6B3 7CC  C #DD DO7'E9 O7E O7 E HO; P//P36P3ct5|rt|dntddddS#1swxYwYdS)z Clear the file operations cache.N)rrr<rsclearr?s rclear_file_ops_cachers $$  $    . . . .  ! ! # # # $$$$$$$$$$$$$$$$$$8A  AArWr%offsetlimitc Z t|rtjdd|diSddl}ddlm}||}|}|dz dz d z |dz dz g}|D]C} | | tjdd |d icS#t$rY@wxYwt|} | ||f} t5t|ddtid } | d i| } dddn #1swxYwY| Q t"j| }|| krtjd|dddSn#t($rYnwxYwt+|}||||}|jrt1|j|_|}t5|jpd}|dd}t7}||kr=|dd}tjd|dd|dd|d|||ddS|rA|t8kr6|dkr0|dr|dd |dd!d"|||f}t5d | vri| d <| d#|||f| d$|kr| d%xxd&z cc<n || d$<d&| d%<| d%} t"j| }|| d | <|| d'i| <n#t($rYnwxYwdddn #1swxYwY|d(krtjd)|d*||d+dS|d,kr d-|d.|d/<tj|dS#t<$r/}tjdt|idcYd}~Sd}~wwxYw)0z-Read a file with pagination and line numbers.errorz Cannot read 'zE': this is a device file that would block or produce infinite output.rN)get_hermes_homeskillsz.hubz index-cachezAccess denied: z is an internal Hermes cache file and cannot be read directly to prevent prompt injection. Use the skills_list or skill_view tools instead.)last_key consecutive read_historydedupruFile unchanged since last read. The content from the earlier read_file result in this conversation is still current — refer to that instead of re-reading.T)contentr%rF ensure_asciirS file_size total_linesunknownzRead produced ,z, characters which exceeds the safety limit (zD chars). Use offset and limit to read a smaller range. The file has z lines total.)rr%rr truncated_hintzThis file is large (zj bytes). Consider reading only the section you need with offset and limit to keep context usage efficient.readrrrrWread_timestampsz.BLOCKED: You have read this exact file region z| times in a row. The content has NOT changed. You already have this information. STOP re-reading and proceed with your task.)rr% already_readz%You have read this exact file region z times consecutively. The content has not changed since your last read. Use the information you already have. If you are stuck in a loop, stop reading and proceed with writing or responding._warning)r+jsondumpspathlibhermes_constantsrrr&resolve relative_tor0str_read_tracker_lockr= setdefaultsetr r$r%getmtimer/r~ read_filerrto_dictlenr_LARGE_FILE_HINT_BYTESaddr)r%rrr?_pathlib_get_hh _resolved _hermes_home _blocked_dirs_blocked resolved_str dedup_key task_data cached_mtime current_mtimer}result result_dict content_lenr max_charsrread_keycount _mtime_nowes rread_file_toolrstVA d # # :8D888  #"""??????MM$''2244<<>> wyy((** 8 #f ,} < 8 #f , &  H %%h///zK$KKK#    9~~ !651  E E%00  #;;I%=="5599)DDL  E E E E E E E E E E E E E E E  #  " 0 0 > >  L00:U!%!%''%*++++1    !))##D&%88 > C26>BBFNnn&& &..B// OOK33 '))  " "%//-CCK:?[N??)2???%0??? *&  " # # # #  )&<<<CKKOOK00  " "73y=333   D&%0   i''%' '" n % ) )4*? @ @ @$00-(((A-(((((0 *%+, -(m,E  W--l;; 0: '"9-LV $$%6;;LII    )               . A:::BUBBB %"### #aZZcccc  # z+E:::: AAAz7CFF+%@@@@@@@@@As(O1A6O1".CO1 C O1C  O1>AE  O1 E$$O1'E$(O1.>F.-O1. F;8O1:F;;CO1AO1%AN=ANN N N NN O1N!!O1$N!%&O1 $O11 P*;$P%P*%P*c t5t|i}|dt}i}|D]6\}}}||vrg||<||d|d||zdz 7dt |DcdddS#1swxYwYdS)zReturn a list of files read in this session for the given task. Used by context compression to preserve file-read history across compression boundaries. rzlines -rWcg|] \}}||d S))r%regions).0prs r z*get_read_files_summary..s4   77 + +   r,N)rr=r rappendsorteditems)r?rr seen_pathsr%rrs rget_read_files_summaryrs2    !%%gr22  }}^SUU;;  %1 L L !T65:%%#% 4 t  # #$JV$J$Jfunq6H$J$J K K K K  $Z%5%5%7%788                      sB#B88B<?B<ct5|rt|dntddddS#1swxYwYdS)zClear the read tracker. Call with a task_id to clear just that task, or without to clear all. Should be called when a session is destroyed to prevent memory leaks in long-running gateway processes. N)rr=rsrrs rclear_read_trackerrs ""  "   gt , , , ,    ! ! ! """"""""""""""""""rc4t5|r;t|}|rd|vr|dn:tD] }d|vr|d!ddddS#1swxYwYdS)uClear the deduplication cache for file reads. Called after context compression — the original read content has been summarised away, so the model needs the full content if it reads the same file again. Without this, reads after compression would return a "file unchanged" stub pointing at content that no longer exists in context. Call with a task_id to clear just that task, or without to clear all. rN)rr=r rvaluesr?rs rreset_file_deduprs //  /%))'22I +W 11'"((****1133 / / i''g&,,...//////////////////sA8B  BBct5t|}|r d|d<d|d<ddddS#1swxYwYdS)uReset consecutive read/search counter for a task. Called by the tool dispatcher (model_tools.py) whenever a tool OTHER than read_file / search_files is executed. This ensures we only warn or block on *truly consecutive* repeated reads — if the agent does anything else in between (write, patch, terminal, etc.) the counter resets and the next read is treated as fresh. Nrrr)rr=r rs rnotify_other_tool_callrs ))!%%g..  )$(Ij !'(Im $ ))))))))))))))))))s'<AAc tt|}tj|}n#ttf$rYdSwxYwt5t |}||| di|<ddddS#1swxYwYdS)uRecord the file's current modification time after a successful write. Called after write_file and patch so that consecutive edits by the same task don't trigger false staleness warnings — each write refreshes the stored timestamp to match the file's new state. Nr) rrr&rr$r%rr/r0rr=r r)r"r?r3rrs r_update_read_timestamprs"tH~~0022::<<==((22 Z  RR!%%g..  DQI !2B 7 7 ARRRRRRRRRRRRRRRRRRs$AA""A76A76CC Cc" tt|}n#tt f$rYdSwxYwt 5t|}|s ddddS|di|}dddn #1swxYwY|dS tj |}n#t$rYdSwxYw||krd|dSdS)uCheck whether a file was modified since the agent last read it. Returns a warning string if the file is stale (mtime changed since the last read_file call for this task), or None if the file is fresh or was never read. Does not block — the write still proceeds. Nrz Warning: z was modified since you last read it (external edit or concurrent agent). The content you read may be stale. Consider re-reading the file to verify before writing.) rrr&rr/r0rr=r r$r%r)r"r?r3r read_mtimers r_check_file_stalenessr stH~~0022::<<== Z tt HH!%%g..  HHHHHHHH]]#4b99==hGG HHHHHHHHHHHHHHH t((22 tt "" L L L L 4s<AAAA"C )CC CC22 D?Drct|}|rtjd|idS t||}t |}|||}|}|r||d<t||tj|dS#t$r}t|r/t dt|j |n0tdt|j |dtjdt|idcYd }~Sd }~wwxYw) zWrite content to a file.rFrrz"write_file expected denial: %s: %szwrite_file error: %s: %sT)exc_infoN)r5rrrr~ write_filerrrr;rvdebugtype__name__rr) r%rr? sensitive_err stale_warningr}rrrs rwrite_file_toolr+s])$//MHz7M2GGGGA-dG<<  ))$$T733nn&&  4&3K # tW---z+E:::: AAA ' * * Y LL=tAww?OQR S S S S LL3T!WW5EqSWL X X Xz7CFF+%@@@@@@@@@ AsA5B!! E+BE=EEreplaceFmode old_string new_string replace_allpatchcg}|r|||dkr_|r]ddl}|d||jD]<} || d=|D]-} t | } | rtjd| idcS. g} |D])} t| |} | r| | *t|}|d krK|stjdd iS||tjdd iS| ||||}nM|dkr.|stjdd iS| |}ntjdd |iS| }| r3t| dkr| dnd| |d<|ds|D]} t#| |tj|d}|drdt%|dvr|dz }|S#t&$r/}tjdt%|idcYd}~Sd}~wwxYw)z4Patch a file using replace mode or V4A patch format.rrNz/^\*\*\*\s+(?:Update|Add|Delete)\s+File:\s*(.+)$rWrFrrz path requiredz"old_string and new_string requiredzpatch content requiredzUnknown mode: z | rzCould not findzp [Hint: old_string not found. Use read_file to verify the current content, or search_files to locate the text.])rrefinditer MULTILINEgroupstripr5rrrr~ patch_replace patch_v4arrjoinr rrr)rr%rrrrr?_paths_to_check_re_m_prstale_warnings_swr}rr result_jsonrs r patch_toolrCs" O %t$$$ w5,,QSXZ]Zghh 8 8B  " "288A;;#4#4#6#6 7 7 7 7LL-b11  L:w 6UKKK K K K L&A! + +B'G44C +%%c*** )) 9   >z7O"<===!Z%7z7,P"QRRR++D*j+VVFF W__ Gz7,D"EFFF''..FF:w(?(?(?@AA Ann&&  t;>~;N;NRS;S;SnQ&7&7Y^YcYcdrYsYsK #w'' 4% 4 4&r73333j5AAA  ??7 # # P(8C G@Tminimumz9Maximum number of lines to read (default: 500, max: 2000)i)rrr>maximum)r%rr)r propertiesrequired)r r parametersuWrite content to a file, completely replacing existing content. Use this instead of echo/cat heredoc in terminal. Creates parent directories automatically. OVERWRITES the entire file — use 'patch' for targeted edits.zWPath to the file to write (will be created if it doesn't exist, overwritten if it does)z%Complete content to write to the file)r%raiTargeted find-and-replace edits in files. Use this instead of sed/awk in terminal. Uses fuzzy matching (9 strategies) so minor whitespace/indentation differences won't break it. Returns a unified diff. Auto-runs syntax checks after editing. Replace mode (default): find a unique string and replace it. Patch mode: apply V4A multi-file patches for bulk changes.zVEdit mode: 'replace' for targeted find-and-replace, 'patch' for V4A multi-file patches)renumrr>z/File path to edit (required for 'replace' mode)zText to find in the file (required for 'replace' mode). Must be unique in the file unless replace_all=true. Include enough surrounding context to ensure uniqueness.z_Replacement text (required for 'replace' mode). Can be empty string to delete the matched text.booleanzLReplace all occurrences instead of requiring a unique match (default: false))rrr>zV4A format patch content (required for 'patch' mode). Format: *** Begin Patch *** Update File: path/to/file @@ context hint @@ context line -removed line +added line *** End Patch)rr%rrrruSearch file contents or find files by name. Use this instead of grep/rg/find/ls in terminal. Ripgrep-backed, faster than shell equivalents. Content search (target='content'): Regex search inside files. Output modes: full matches with line numbers, file paths only, or match counts. File search (target='files'): Find files by glob pattern (e.g., '*.py', '*config*'). Also use this instead of ls — results sorted by modification time.zPRegex pattern for content search, or glob pattern (e.g., '*.py') for file searchfileszK'content' searches inside file contents, 'files' searches for files by namezCDirectory or file to search in (default: current working directory)zOFilter files by pattern in grep mode (e.g., '*.py' to only search Python files)z1Maximum number of results to return (default: 50)z0Skip first N results for pagination (default: 0))r files_onlyrzOutput format for grep mode: 'content' shows matching lines with line numbers, 'files_only' lists file paths, 'count' shows match counts per filezDNumber of context lines before and after each match (grep mode only))rrr%rrrrrc |dpd}t|dd|dd|dd| S) Nr?r>r%rSrrWrr)r%rrr?)r rargskwtids r_handle_read_filer+s_ &&   (yC txx33DHHXqr%rSr)r%rr?)r rr's r_handle_write_filer-sK &&   (yC  4 4dhhyRT>U>U_b c c ccr,c D|dpd}t|dd|d|d|d|dd |d | S) Nr?r>rrr%rrrFr)rr%rrrrr?)r rr's r _handle_patchr/"s &&   (yC  XXfi ( (txx/?/?88L))dhh|6L6LHH]E22$((7:K:KUX Z Z ZZr,c |dpd}ddd}|dd}|||}t|dd||d d |d |d d |dd|dd|dd| S)Nr?r>rr$)grepfindrrrSr%rrrrrrrr) rrr%rrrrrr?)r r )r(r)r* target_map raw_targetrs r_handle_search_filesr5*s &&   (yC#W55J(I..J ^^J 3 3F B''TXXfc=R=R((;''txx/D/DTXXV^`aMbMbHH]I66TU@V@V`c e e eer,fileu📖)r toolsetschemahandlercheck_fnemojiu✍️u🔧u🔎)r>)N)rWrr>)rNNNFNr>)rrNrrrrr>)D__doc__r9rloggingr$rtrrtools.file_operationsr agent.redactr getLoggerrrvEACCESEPERMEROFSr:rrr__annotations__rr frozensetr'rboolr+r1r2r5rr;rurrr<dictrr=r~rrlistrrrrrrrrr rrtools.registryrrREAD_FILE_SCHEMAWRITE_FILE_SCHEMA PATCH_SCHEMASEARCH_FILES_SCHEMAr+r-r/r5registerrr,rrOs<<<  555555......  8 $ $ , U[A"%)d )))"S""""0! " # # #  *D02DECC$J(iD !!"$Y^%% tvv3v/Bvvvvr$$#$$$$XAXAXAcXAcXA#XA^aXAXAXAXAv  C     ( " " " " " "//c////, ) )C ) ) ) ) RSR3R4RRRR$C##*>AA#AAcA#AAAA0KOOS'6A6AS6AC6AC6A6A486AIL6A6A,/6A6A6A6ArDGFG=>(AAAAAAcAASAAAA.1AA@CAA AA7:AAAA.1AAAAAAAAJn55 77 *-- 55  $#####%%% c%6pqq(9tBCPQRR'8sADQUVV  H   p%7PQQ (9`aa  Y'    B% 7/CUmzCDD%6ghh#+=cdd#+=^__$-?MZ_``&8uvv   H   $ O (:LMM')W1EWdqz{{%6{ILMM"*Q[o{KSYZZZZZZr,