epj3dZddlZddlZddlZddlZddlmZddlmZm Z m Z m Z ddl m Z ejeZgdZdZhdZd hZd Zehd Zd ed edefdZGddZdS)aProgressive subdirectory hint discovery. As the agent navigates into subdirectories via tool calls (read_file, terminal, search_files, etc.), this module discovers and loads project context files (AGENTS.md, CLAUDE.md, .cursorrules) from those directories. Discovered hints are appended to the tool result so the model gets relevant context at the moment it starts working in a new area of the codebase. This complements the startup context loading in ``prompt_builder.py`` which only loads from the CWD. Subdirectory hints are discovered lazily and injected into the conversation without modifying the system prompt (preserving prompt caching). Inspired by Block/goose's SubdirectoryHintTracker. N)Path)DictAnyOptionalSet)_scan_context_content)z AGENTS.mdz agents.mdz CLAUDE.mdz claude.mdz .cursorrulesi@>pathworkdir file_pathterminal>.hg.git.svn.tox.venv.Trash.cache.backups .mypy_cache .pytest_cache dist-packages site-packagesvenvbackupvendorbackups __pycache__ third_party node_modulesabreturncT ||dS#t$rYdSwxYw)zKCheck if *a* is the same as or an ancestor of *b* (parent directory check).TF) relative_to ValueError)r!r"s >/home/thesage/.hermes/hermes-agent/agent/subdirectory_hints.py_is_ancestor_or_samer(>s@ at uus  ''ceZdZdZddeefdZddZdedeee fdeefd Z ded eee fde fd Z d ed e efdZded e efdZdedefdZdedefdZdedeefdZdS)SubdirectoryHintTrackerasTrack which directories the agent visits and load hints on first access. Usage:: tracker = SubdirectoryHintTracker(working_dir="/path/to/project") # After each tool call: hints = tracker.check_tool_call("read_file", {"path": "backend/src/main.py"}) if hints: tool_result += hints # append to the tool result string N working_dirc*t|ptj|_t |_t |_|j|j| dSN) rosgetcwdresolver+set _loaded_dirs_loaded_digestsadd_seed_working_dir_digest)selfr+s r'__init__z SubdirectoryHintTracker.__init__Tsu :ry{{;;CCEE'*uu*- d./// %%'''''r#ctD]}|j|z } |s"|d}n#t t f$rY^wxYw|rQ|jtj | d dSdS)atRecord the CWD context file's digest so it is never re-injected. ``prompt_builder`` already loads the working directory's context file at startup. Seeding its digest here means the same content reached through a different path (a symlink farm, a shared workspace) is recognised as a duplicate instead of being sent a second time. utf-8encodingN) _HINT_FILENAMESr+is_file read_textstripOSErrorUnicodeDecodeErrorr3r4hashlibsha256encode hexdigest)r6filename candidatecontents r'r5z0SubdirectoryHintTracker._seed_working_dir_digest^s(  H(83I  ((**#--w-??EEGG/0     $((N7>>'#:#:;;EEGG EE  sA(AA'&A' tool_name tool_argsc|||}|sdSg}|D].}||}|r||/|sdSdd|zS)zCheck tool call arguments for new directories and load any hint files. Returns formatted hint text to append to the tool result, or None. N )_extract_directories_load_hints_for_directoryappendjoin)r6rJrKdirs all_hintsdhintss r'check_tool_callz'SubdirectoryHintTracker.check_tool_callts((I>> 4  ( (A22155E (  ''' 4 I....r8argsct}tD]V}||}t|tr*|r|||W|tvrA|dd}t|tr|||t|S)z1Extract directory paths from tool call arguments.command) r1_PATH_ARG_KEYSget isinstancestrr@_add_path_candidate_COMMAND_TOOLS_extract_paths_from_commandlist)r6rJrW candidateskeyvalcmds r'rNz,SubdirectoryHintTracker._extract_directoriess!$ " : :C((3--C#s## :  :((j999  & &((9b))C#s## B00jAAAJr8raw_pathrcc t|}|s |j|z }|}|js(|r|r|j}ttD]J}||j vrdS| |r| ||j}||krdS|}KdS#ttt f$rYdSwxYw)aResolve a raw path and add its directory + ancestors to candidates. Walks up from the resolved directory toward the filesystem root, stopping at the first directory already in ``_loaded_dirs`` (or after ``_MAX_ANCESTOR_WALK`` levels). This ensures that reading ``project/src/main.py`` discovers ``project/AGENTS.md`` even when ``project/src/`` has no hint files of its own. N)r expanduser is_absoluter+r0suffixexistsr>parentrange_MAX_ANCESTOR_WALKr2_is_valid_subdirr4rAr& RuntimeError)r6rgrcp_rms r'r_z+SubdirectoryHintTracker._add_path_candidates X))++A==?? )$q( Ax AHHJJ 199;; H-..  )))EE((++&NN1%%%Q;;EE  \2    DD sB)C,-8C,'C,,DDrfc tj|}n$#t$r|}YnwxYw|D]M}|drd|vrd|vr!|dr7|||NdS)z5Extract path-like tokens from a shell command string.-/.)zhttp://zhttps://zgit@N)shlexsplitr& startswithr_)r6rfrctokenstokens r'raz3SubdirectoryHintTracker._extract_paths_from_commands ![%%FF ! ! !YY[[FFF ! 8 8E$$ %Cu$4$4 ?@@   $ $UJ 7 7 7 7 8 8s 88r c6 |sdSn#t$rYdSwxYw||jvrdS ||jsdSn/#tt f$rt |j|sYdSYnwxYw||rdSdS)aTCheck if path is a valid directory to scan for hints. Only allow subdirectories within the working directory tree. This prevents loading AGENTS.md from outside the active workspace (e.g. ~/.codex/AGENTS.md, ~/.claude/CLAUDE.md), which causes cross-agent context contamination and instruction mixup. FT)is_dirrAr2is_relative_tor+r&r( _is_excluded)r6r s r'rpz(SubdirectoryHintTracker._is_valid_subdirs ;;== u    55  4$ $ $5  &&t'788 u $   ((8$?? uu      T " " 5ts ''A&A?>A?c ||jj}n#t$rYdSwxYwt d|DS)u:True when the path sits inside a directory that holds copies, not context. Directories the user is deliberately working inside are never excluded — if ``working_dir`` is itself under ``vendor/``, that segment is legitimate and only segments *below* the working dir are screened. Tc3(K|] }|tvVdSr-)_EXCLUDED_DIR_NAMES).0parts r' z7SubdirectoryHintTracker._is_excluded..s(EE44..EEEEEEr8)r%r+partsr&any)r6r rel_partss r'rz$SubdirectoryHintTracker._is_excludedse (()9::@II   44 EE9EEEEEEs " 00 directorycb|j| ||js#td||jdSnP#t tf$r<t|j|s$td||jYdSYnwxYwg}tD]}||z } | sn#t $rY+wxYw | d }|s[tj|d}||jvr'td||ddnV|j|t%||}t'|t(kr'|dt(d|dt'|d d z}t+|} t+||j}nh#tt.f$rT t+|t1j}d |z}n#tt.f$rYnwxYwYnwxYw|||fn4#t6$r'}td ||Yd}~d}~wwxYw|sdSg} |D] \}}| d |d|!td|d|Dd| S)zLoad hint files from a directory. Returns formatted text or None. Only loads hints from directories within the working directory tree. u4Skipping hint files in %s — outside working_dir %sNr:r;z1Skipping duplicate hint content at %s (digest %s) z [...truncated z: ,z chars total]z~/zCould not read %s: %sz"[Subdirectory context discovered: z] z%Loaded subdirectory hints from %s: %scg|] }|d S)r)rhs r' zESubdirectoryHintTracker._load_hints_for_directory..Rs ' ' 'aQqT ' ' 'r8rM)r2r4rr+loggerdebugrAr&r(r=r>r?r@rCrDrErFr3rlen_MAX_HINT_CHARSr^r%rqrhomerP ExceptionrQ) r6r found_hintsrG hint_pathrIdigestrel_pathexcsectionss r'rOz1SubdirectoryHintTracker._load_hints_for_directorys i((( ++D,<==  Jt/t   $   '(8)DD  Jt/tt     '- F- FH!H,I  ((**    & F#--w-??EEGG !w(?(?@@JJLLT111LLK!ss  E$((000/BBw<>"9#8#89I#J#JKKHH"L1#&y'<'/ # ////0  $(cN     (CSY<8s8D 8888&Td> F F$ F F F FU%4U%HSMU%U%U%U%U%U%r8r*)rrCloggingr.rxpathlibrtypingrrrragent.prompt_builderr getLoggerrrr=rr[r`ro frozensetrrr(r*rr8r'rsM   ++++++++++++666666  8 $ $ 211  i!!!DTdM%M%M%M%M%M%M%M%M%M%r8