߲j ZUdZddlZddlZddlZddlZddlZddlmZmZddl m Z m Z m Z m Z mZmZmZddlmZmZmZmZej,eZdddd Zed Zed Zd Zd ZdZdZ dedee!fdZ"dedee!dffdZ#dede$fdZ%dedee!fdZ&dddeede$fdZ'dddeede$fdZ(da)de!fdZ*de!dee e!e fe!ffdZ+de de$fdZ,d e e!e fde$fd!Z-iZ.e e!e$fe/d"<de$fd#Z0de$fd$Z1e0e1d%d&Z2e e!e ge$ffe/d'<d(e!de$fd)Z3d e e!e fde$fd*Z4d e e!e fde$fd+Z5iZ6e ee!e7e7e7e7fe e!e ffe/d,<dud-Z8d.edeee!e7e7e7e7ffd/Z9de e!e ffd0Z:dee e!e ffd1Z;d2e!de fd3Zed8hZ?ee/d9<dvd:e!dzdee!fd;Z@de e!fd<ZAdee!fd=ZBiZCe ee!e7e7e7e7fe efe/d><dud?ZDde e!fd@ZEde efdAZFdeefdBZGde!fdCZHde efdDZIejjdEdFejjdGdFfZLdHZMdvdIeedeefdJZNdeefdKZOdede$fdLZPdede efdMZQdNe$deefdOZRde efdPZSdeeee7ffdQZTdRZUiZVe e!e$fe/dS<de$fdTZWdUefdVZXdWe!de!fdXZYdefdYZZde$fdZZ[d e e!e fde e!e ffd[Z\d\Z]d e e!e fde e!e ffd]Z^d e e!e fde e e!e ffd^Z_de e e!e ffd_Z`d`Zadae e!e fdbe!fdcZbejddZddee!de!fdfZedge e e!e fde e!e ffdhZfdiZgd e e!e fde!fdjZhd e e!e fde!fdkZid e e!e fde$fdlZjdedme!fdnZkejdoZldpe!deee!e!ffdqZmdree!de$fdsZnde efdtZoy)wzLightweight skill metadata utilities shared by prompt_builder and skills_tool. Import-light by design: no tool registry, CLI config, or provider resolution.N)PathPurePath)AnyCallableDictListOptionalSetTuple)get_config_pathget_skills_dirget_subprocess_home is_termuxdarwinlinuxwin32)macosrwindows).gitz.githubz.hubz.archivez.curator_backupsz.locksz.venvvenv node_modulesz site-packages __pycache__z.toxz.noxz .pytest_cachez .mypy_cachez .ruff_cache) references templatesassetsscripts_orgz .active_orgz.org-provenance.jsonz.org-baseline.json skills_dirreturnc|tz tz } |jr$|jdj xsdSdS#t $rYywxYw)zBThe org id whose mirror may resolve, or None (no org skills load).utf-8encodingN)ORG_MIRROR_DIR_NAMEORG_ACTIVE_MARKERexists read_textstripOSError)rmarkers 6/home/ubuntu/.hermes/hermes-agent/agent/skill_utils.pyread_active_org_idr,*sZ - -0A AFGM}}  ' 288:Bd`\`` s3AA AA.c t|jjt|jj}|r|dt k(r|SdS#tt f$rYywxYw)zTPath parts of *path* relative to *skills_dir* if it is under ``_org/``, else ``()``.r)rresolve relative_topartsr) ValueErrorr$pathrr1s r+_org_rel_partsr53slT ""$00j1A1I1I1KLRReAh*==5E2E Z sA AA/.A/c,tt||S)z6True when *path* is inside the org mirror (``_org/``).)boolr5)r4rs r+is_org_mirror_pathr8<s tZ0 11cDt||}t|dk\r|dSdS)z@The ```` segment for a path under ``_org//...``.N)r5lenr3s r+org_id_of_pathr>As' 4 ,E5zQ580D0r9rootr@ctt|j}td|Dxs t ||S)zTrue if *path* should be skipped by skill scanners (VCS/dependency/cache dirs + support packages). Apply to every SKILL.md from a direct ``rglob``.c3,K|] }|tvywN)EXCLUDED_SKILL_DIRS).0parts r+ z)is_excluded_skill_path..Ks=tt**=sr?)rstrr1anyis_skill_support_path)r4r@r1s r+is_excluded_skill_pathrKGs8 SY  % %E =u= = gAVW[bfAggr9ct|tr|ntt|}|j||j s|n tt fdt ddDS)zTrue if *path* is under a support dir sitting directly inside a skill root (``skills/scripts/foo`` stays discoverable: no ``SKILL.md`` above ``scripts``).Nc3K|]5\}}|dkDr+|tvxrtd|z dz j7yw)rNSKILL.md)SKILL_SUPPORT_DIRSrr&)rEidxrFbaser1s r+rGz(is_skill_support_path..UsP C 7 ""XtU4C[/A(AJ(N'V'V'XXs;>) isinstancerrHr1 is_absoluterI enumerate)r4r@path_objrQr1s @@r+rJrJNsd"$-t4D ?H NNE#H,@,@,B4D "5":. r9contentct>ddl}ddl}|j|jt |ddxs |j at|S)z7Parse YAML with lazy import and CSafeLoader preference.Nr CSafeLoader)Loader) _yaml_load_fn functoolsyamlpartialloadgetattr SafeLoader)rWr\r]s r+ yaml_loadrb_sJ!))$))GD-Y]<^rs&"''-- *Xbggmm True). Cached per process EXCEPT ``kanban``: that verdict is context-dependent (delegate children / in-process cron see the worker's vars), so a process-wide cache would leak the first asker's answer to the others.rT)rrr)rdetectorresults r+_detect_environmentrsI  h3"33 %%!!#&H#XZF#c Mr9c|jd}|syt|tr|n|gDcgc])}t|j j +}}t d|DScc}w)zzTrue when ANY declared ``environments:`` tag is active (absent = all; unknown tags fail open). Offer-time filter only. environmentsTc38K|]}|st|ywrC)r)rEtags r+rGz,skill_matches_environment..s?C3"3'?s)rrSr}rHr~r(rI)rsrrtagss r+skill_matches_environmentrsf??>2L AKLZ^A_fres uCHNN  " " $ uD u ?4? ?? vs.A.c|jd}|syddlm}ddlm}t |t r|n|gD]N}|jt|j}| |jy||jrNyy)aTrue when every app named in ``requires_apps:`` has a registered declaration this host satisfies. Names resolve through ``hermes_platform.declaration`` (registered by whoever owns the server, e.g. the plugin loader); the check is the same ``availability()`` the MCP check_fn uses. An unknown name hides the skill (fail closed). Offer-time filter, like ``environments:``. requires_appsTr) declaration) availabilityF) rhermes_platformr%hermes_platform.resolver.availabilityrrSr}lookuprHr(app offerable)rsnamesrrnamedecls r+skill_matches_appsrs| OOO ,E +B#E40ug!!#d)//"34 <488+D!++  r9_RAW_CONFIG_CACHEc,tjy)u/Test hook — drop the shared raw config cache.N)rclearr.r9r+_raw_config_cache_clearrsr9 config_pathct ddlm}t|g||jS#t$rYywxYw)zT``(path, *file_signature)`` identity of config.yaml, or None when unreadable/absent.r)file_signatureN)utilsrrHstatr))rrs r+_config_cache_keyrs=(K F>+2B2B2D#EFF s (+ 77ct}|jsiSt|}|tj |nd}||S t |j d}t|tsiS|tj|t|<|S#t$r#}tjd||icYd}~Sd}~wwxYw)zNRead config.yaml with an mtime+size keyed cache (no hermes_cli.config import).Nr!r"z"Could not read skill config %s: %s) r r&rrrrbr'rnloggerdebugrSrmr)r cache_keycachedrtes r+_load_raw_configrs!#K     !+.I1:1F  " "9 -DF  ;00'0BC fd # !'-)$ M  9;J sB CB;5C;Cc\tjd}t|tr|SdS)zHThe ``skills:`` mapping from config.yaml, or None when absent/malformed.skillsN)rrrSrm) skills_cfgs r+ _skills_cfgrs)!#''1J#J5:?4?r9rvc@t}||j|SdS)zP``skills.`` from config.yaml, or None when the section is absent/malformed.N)rr)rvrs r+_skills_cfg_getrs"J","8:>># BdBr9entrycttjjtjj |S)z3Expand ``~`` and ``${VAR}`` in a config path entry.)rrr4 expanduser expandvars)rs r+ _expand_pathrs+ ""277#5#5e#<= >>r9pcFddlm}|jr|S||z S)zJAnchor a relative config path at HERMES_HOME; absolute paths pass through.rget_hermes_home)rrrT)rrs r+_home_relativer!s 0 1:_%6%::r9z hermes-agentESSENTIAL_SKILLSrc6t}| tSddlm}|xst j dxs|d}t |jd}|r$|jdxsij|nd}||t |z}|tz S)uDisabled skill names from config.yaml: global list ∪ platform list (*platform* defaults to ``HERMES_PLATFORM`` / ``HERMES_SESSION_PLATFORM``).Nr)get_session_envHERMES_PLATFORMHERMES_SESSION_PLATFORMdisabledplatform_disabled) rsetgateway.session_contextrrr_normalize_string_setrr)rrrresolved_platformrrs r+get_disabled_skill_namesr,sJu 7 nBII.?$@nOTmDn$Z^^J%?@H^o(;<BGGHYZuy$)*;<< & &&r9ct|tro|jjdrM t j |j}t|tr|Dcgc] }t|c}S|gSt|ttttfr|Dcgc] }t|c}SgS#t tf$rd}YzwxYwcc}wcc}w)aNormalize a config value that may hold a JSON-array string into a list. ``hermes config set`` stores lists as quoted JSON/Python-literal strings; treating one as a single name would silently filter nothing. A scalar string still means one name. See #13026, #86661. [N) rSrHr(rhast literal_evalr2 SyntaxErrorr}tupler frozenset)rwrtitems r+parse_config_string_listr;s% ;;= # #C ( ))%++-8&$'.45dD 55w,6utUCQZ>[,\% ($CI (dbdd  ,  6 (s#B;(C$C;CCc|t|Dchc]#}|js|j%c}Scc}wrC)rr()valuesrs r+rrOs)%=f%E VTDJJL VV Vs99_EXTERNAL_DIRS_CACHEc@tjty)u(Test hook — drop the in-process cache.N)rrrr.r9r+_external_dirs_cache_clearrXs r9ct|tr|g}t|tsgSd|DDcgc]}|s| c}Scc}w)zFA scalar-or-list config entry as a list of stripped non-empty strings.c3NK|]}t|jywrC)rHr()rErs r+rGz#_config_str_list..ds.sGa$Gs )r rrrextendr)rrs @r+get_all_skills_dirsrsP   D%'J*"3"3"5 JKKG35GG Kr9z.hermesrz.agents@rkc| | ddlm}|}t|j}tj j} t tD]?}|dz jr ||k(rdcS|cS|j|k(ry|j}A y#t$rYywxYw#t$rYywxYw)uNearest ancestor containing ``.git`` (dir or worktree file), or None. Without *start*, the surface's effective working directory wins over the process cwd — the same ladder every other cwd consumer reads (``resolve_agent_cwd``: session-bound cwd, then the scope's ``TERMINAL_CWD``, then the process cwd). The session cwd comes first because a multi-session host (TUI/desktop gateway) pins each session's workspace there while its terminal scope resolves a placeholder ``terminal.cwd`` to ``$HOME``; reading only the scope made every project skill invisible on those surfaces (#114359). ``TERMINAL_CWD`` is the per-surface workdir the terminal tool and cron jobs use (a cron job sets it from its per-job ``workdir`` without chdir'ing the scheduler process), which lets non-interactive surfaces inherit a prior interactive trust decision by project identity — and a surface with no workdir in a trusted repo simply resolves no project and loads nothing (#48975). Nr)resolve_agent_cwdr) agent.runtime_cwdrrr/r)r range_PROJECT_ROOT_MAX_DEPTHr&parent)rkrcurr _s r+find_project_rootrs = ;%'E5k!!# 99;   D  ./ Af $$& #d{t33zzS **C       s5(B -B/;B/?B/B/ B,+B,/ B;:B;ct}ttdD]+} |jt |j -|S#t $rY;wxYw)zKResolved set of trusted project roots from ``skills.trusted_project_dirs``.trusted_project_dirs)rrraddrr/r))rrs r+!_project_trusted_dirs_from_configr!s]F!/2H"IJ  JJ|E*224 5 M   s(A AAch t|jtvS#t$rYywxYw)z>True when *root* is listed in ``skills.trusted_project_dirs``.F)rr/r!r)r?s r+is_project_root_trustedr#s5Dz!!#'H'JJJ s "% 11ctj}g}fdtDD]E} |jr2|j|k7r|j |jG|S#t $rYUwxYw)zExisting skill dirs under *root*, excluding the profile's own skills dir (HERMES_HOME itself may live inside a git checkout).c3(K|] }|z  ywrCr.)rEsubr@s r+rGz1_candidate_project_skills_dirs..s>>s)r r/PROJECT_SKILLS_SUBDIRSrrr))r@rrcands` r+_candidate_project_skills_dirsr)sy"#++-LD>'=> {{}.sJqJs rN)r-r)sumiter_skill_index_filesr))r@countrs r+!get_untrusted_project_skills_rootr6 sv  /D E595E +D 12  SJ$:1j$IJJ JE "D%=+t+   sA  AAz project-local_PROJECT_QUARANTINE_CACHEct|j} t|j}|t vr t |S ddlm}ddlm }|dz dz }||t|\}}|jdk(}|r!tjd||j|t |<|S#t$rt|}YwxYw#t$rtjd |d d }YJwxYw) uTrue when a project skill's scan verdict is ``dangerous``. Fail-closed: a scanner crash or missing scanner quarantines the skill. Scans unconditionally — non-project callers should not call this.r)scan_skill_cachedrcacheproject_skill_scans)source cache_dir dangerousu8Project skill quarantined (verdict=dangerous): %s — %su<Project skill scan failed — quarantining (fail closed): %sT)exc_info)rrrHr/r)r7tools.skills_guardr9rr_PROJECT_SCAN_SOURCEverdictrwarningsummaryrn) skill_md skill_dirrvr9rr=r_prov quarantineds r+is_quarantined_project_skillrI+sX%%I)##%& ''(-- 84#%/2GG )).IsraRnopRqrsrNN)r4)rJs r+iter_project_skill_filesrMEss1+zJrrrs !! identifierc|xsdj}|s|St|j}|js|j dS ddlm}|j}|g}ttfD]} |j||D]/}|j|st|j|cS t|j!j|j!S#t$r t}YwxYw#t$rYwxYw#t$rt"j%d||cYSwxYw)zTranslate a trusted absolute skill path (slash commands / cron may store them) to the relative form ``skill_view()`` accepts.rr r) skills_toolu~Skill identifier %r is an absolute path outside trusted skills roots — passing through unchanged (skill_view will reject it))r(rrrTlstriptoolsrP _skills_dirrnr r0rrr rHr0r/rr)rNraw_identifieridentifier_path _skills_tool primary_root trusted_rootsgetterr@s r+normalize_skill_lookup_namerZLsS!&B--/N >*557O  & & ($$S)) (5#//1 "NM*,DE    *:  ) )$ /22489 9:?**,889M9M9OPQQ (%' (      WXf hs6D=D 5D(DD D%$D%(!E  E ct|tr|ntt|} |jj S#t t f$r!|jjcYSwxYwrC)rSrrHrr/r) RuntimeErrorabsolute)r4rVs r+_resolve_for_skill_ownershipr^ssc!$-t4D ?H0""$,,.. \ "0""$--//0sA-A65A6ct|tt} |jt t fd|DS#t $rYwxYw)zTrue when ``path`` lives under an external or trusted project skills dir. Those are externally owned: autonomous lifecycle maintenance treats them as read-only (user-directed tool calls may still edit them).c3RK|]}jt| ywrC)r r^)rEr@ candidates r+rGz)is_external_skill_path..s#^PTy''(DT(JK^s$')r^r}rrr0rnrI)r4rootsras @r+is_external_skill_pathrc{sZ-T2I578E  ,./ ^X]^ ^^    sA AAc|jd}t|tr|jdnd}t|tr|SiS)zG``metadata.hermes`` mapping from frontmatter, or ``{}`` when malformed.metadatahermesN)rrSrm)rsrerfs r+_hermes_metadatargs=z*H'1(D'AX\\( #tF-6525r9)fallback_for_toolsetsrequires_toolsetsfallback_for_toolsrequires_toolssession_platformsclt|}tDcic]}||j|gc}Scc}w)zPExtract conditional activation fields from parsed frontmatter (absent = ``[]``).)rg_CONDITION_KEYSr)rsrfrvs r+extract_skill_conditionsros0 k *F0? @CC$ $ @@ @s1crt|jd}t|tr|g}|rt|tsgSi}|D]}t|tst |jddj }t |jddj }|r||vs|so||d}|jd|d|d<|jd}t|t r |j r|j n||d<|||<t |jS)zExtract ``metadata.hermes.config`` declarations (key/description/default/prompt). Entries missing ``key`` or ``description`` are skipped; ``prompt`` defaults to the description.configrvr description)rvrrdefaultprompt)rgrrSrmr}rHr(r)rsrrrrvdescr prompt_texts r+extract_skill_config_varsrws! ; ' + +H 5C#te jd+ (*F $% $((5"%&,,.488M2./557cVm4 (+D A 88I  *#IE) hhx( 1;K1MR]RcRcRe+++-kohs      r9ci}t}tD]}|jst|dD]} t |j d\}}t|jdxs|jj}||vs t|sdt|D]}|d|vs ||d<|||d<t|jS#t $rYwxYw)zConfig var declarations across all enabled, platform-compatible skills, deduplicated by key; each dict carries a ``skill`` attribution key.rNr!r"rrvskill)rrrr4rxr'rnrHrrrrrwr}r)all_varsrr skill_filersr skill_namevars r+discover_all_skill_config_varsr~s+-H')H)+/   " 0ZH /J !2:3G3GQX3G3Y!Z Q[__V4N 8I8I8N8NOJX%-CK-P0= /u:X-#-CL+.HSZ( / // ! ""  sC C)(C)z skills.configrq dotted_keycl|}|jdD]}t|tr||vry||}|S)zGWalk a nested dict following a dotted key; None if any part is missing..N)rorSrm)rqrcurrentrFs r+_resolve_dotpathrsEG  % '4(D,?$-  Nr9z\$(?:\{HOME\}|HOME)(?=$|[/\\])rwctr7|dk(s|jdr|ddz}tjfd|}tj j tj j|S)alExpand ``~`` / ``$HOME`` against the HOME Hermes injects into tool subprocesses. Skill config defaults describe paths the agent hands to tools, so in a container where the control process HOME (``/opt/data``) differs from the tool HOME (``{HERMES_HOME}/home``) a plain ``expanduser`` pointed the prompt at a path no tool would ever read (#12260). ~)rz~\r<NcSrCr.)_msubprocess_homes r+rz+_expand_skill_config_path..sOr9)rrh _HOME_VAR_REr&rr4rr)rwrs @r+_expand_skill_config_pathrsm*+O C<5++M:#eABi/E  !;UC 77  bgg007 88r9 config_varsct}i}|D]y}t|td|d}| t|tr"|j s|j dd}t|trd|vsd|vr t|}|||d<{|S)zMap logical skill config keys to current values (or declared defaults); path-like string values are ``~``/``$HOME``/``${VAR}`` expanded against the tool HOME.rrvrsrr$)rrSKILL_CONFIG_PREFIXrSrHr(rr)rrqrr}rws r+resolve_skill_config_valuesrs F!H% ,?+@#e*)NO =Zs3EKKMGGIr*E eS !se|se|-e4E$U % Or9<c~|jdd}|r(t|jjdSdS)z@Normalize a skill's description field for comparison/truncation.rrrz'")rrHr()rsraw_descs r+_normalize_skill_descriptionrs7}b1H193x=   & &u -ArAr9c^t|}t|tkDr|dtdz dzS|S)zCExtract a system-prompt-length description from parsed frontmatter.Nrdz...)rr=SKILL_PROMPT_DESC_LIMIT)rsrus r+extract_skill_descriptionrs7 ' 4D9 !&9T&AjFX KK+ , X "&:Q!z/q:DG"va/B&BL]^bt]t1vQ u  NN277<<h7 894))) ;v*sCB D/ D#D# D/( D(6 D(D( D/A D/D-D/z^[a-zA-Z0-9_-]+$rc@|jd\}}}|r||fSd|fS)zcSplit ``'namespace:skill-name'`` into ``(namespace, bare_name)``; ``(None, name)`` without ``':'``.rfN) partition)r namespacesepbares r+parse_qualified_namer(s->>#.IsD #It 5$5r9racXt|xrttj|S)zDCheck whether *candidate* is a valid namespace (``[a-zA-Z0-9_-]+``).)r7 _NAMESPACE_REmatch)ras r+is_valid_namespacer.s!  ? CtM$7$7 $BCCr9c^tt}|jt|S)uAll skill dirs in precedence order: project → local → external. First-wins name deduplication over this order gives project skills priority over profile-local and external ones. )r}r0rr)rs r+get_scan_ordered_skills_dirsr8s' ') *DKK#%& Kr9)rNrC)p__doc__rloggingrrirpathlibrrtypingrrrrr r r rr r rr getLogger__name__rrrrDrOr$r%ORG_PROVENANCE_FILEORG_BASELINE_FILErHr,r5r7r8r>rKrJr[rbrxrrr__annotations__rrrrrrrintrrrrrrrrrrrrrrrrr rr4rr'rrr!r#r)r-r0r6rAr7rIrMrZr^rcrgrnrorwr~rrcompilerrrrrrrr4rrrrr.r9r+rsQ  "BBB   8 $!GH !OP !,(4HSMFTFeCHoF22$2 1T1hsm1 <@h(4.hDh;? $ 4  "s"suT#s(^S-@'A. 3 4 ES#XE4E&(4T ?'& X1S(2t8,,- S T @4S>@d@DcNt,KM4c3S#56S#XFGL 4HU3S#s;R5S,T$sCx.,@Xd38n-@ CCC ??? ;d;t;((89)9 'sTz 'SX 'etCye(WSXW JLd5c3S!894:EFK CT#YC$t*:htn( '# 'T$Z"'',,y(;RWW\\)U]=^_Xd^x~D3t9$4  $t* [4[HTN[LdL ,8E$)4D+E ,8'-/4T ?/d4s$s$C$C$N0$0 _D _6$sCx.6T#s(^6~A$sCx.AT#t)_A !4S>!d4S>>R!2#T#s(^(<#0&T#s(^rzz;< 9S9S9" T$sCx.-A d3PS8n Bd38nBB g4S>gcg T4S>TdT *t*s*, ./ 6s6uXc]C-?'@6 D(3-DDDd4jr9