#jT^UdZddlZddlZddlZddlZddlmZddlmZm Z m Z m Z m Z m Z ddlmZmZmZejeZdddd Zed Zd efd Zdad efdZd ed e e eefeffdZde eefd efdZehdZiZ e eefe!d<ded efdZ"de eefd efdZ#d0dedzd e efdZ$d e efdZ%iZ&e e ee'fe efe!d<d1dZ(d e efdZ)d e efdZ*de eefd e ee ffdZ+de eefd e e eeffdZ,d e e eeffd Z-d!Z.d"e eefd#efd$Z/d%e e eefd e eeffd&Z0de eefd efd'Z1d(ed)efd*Z2ej3d+Z4d,ed e e eeffd-Z5d.e ed efd/Z6dS)2aLightweight skill metadata utilities shared by prompt_builder and skills_tool. This module intentionally avoids importing the tool registry, CLI config, or any heavy dependency chain. It is safe to import at module level without triggering tool registration or provider resolution. N)Path)AnyDictListOptionalSetTuple)get_config_pathget_skills_dir is_termuxdarwinlinuxwin32)macosrwindows)z.gitz.githubz.hubz.archivez.venvvenv node_modulesz site-packages __pycache__z.toxz.noxz .pytest_cachez .mypy_cachez .ruff_cachereturnc |j}n3#t$r&ddlm}|t |j}YnwxYwt d|DS)aETrue if any component of *path* is in EXCLUDED_SKILL_DIRS. Use this on every SKILL.md path produced by ``rglob`` to prune dependency, virtualenv, VCS, and cache directories. Centralising the check here keeps every skill-scanning site in sync with the shared exclusion set. Accepts a Path or string. r)PurePathc3(K|] }|tvVdSNEXCLUDED_SKILL_DIRS).0parts 6/home/ubuntu/.hermes/hermes-agent/agent/skill_utils.py z)is_excluded_skill_path..>s(==tt**======)partsAttributeErrorpathlibrstrany)pathr!rs ris_excluded_skill_pathr'/sx*  ***$$$$$$T##)* ==u=== = ==s  -::contentct,ddltddpjdtffd }|at|S)z7Parse YAML with lazy import and CSafeLoader preference.Nr CSafeLoadervaluec2|S)N)Loader)load)r+loaderyamls r_loadzyaml_load.._loadNs99U6922 2r ) _yaml_load_fnr0getattr SafeLoaderr$)r(r1r/r0s @@r yaml_loadr5Fsl }d33Ft 3 3 3 3 3 3 3 3  ! !!r cXi}|}|ds||fStjd|dd}|s||fS|d|dz}||dzd} t |}t |tr|}n#t$rt| dD]I}d|vr| dd\}}| || <JYnwxYw||fS)zParse YAML frontmatter from a markdown string. Uses yaml with CSafeLoader for full YAML support (nested metadata, lists) with a fallback to simple key:value splitting for robustness. Returns: (frontmatter_dict, remaining_body) z---z \n---\s*\nN :) startswithresearchstartendr5 isinstancedict Exceptionstripsplit) r( frontmatterbody end_match yaml_contentparsedlinekeyr+s rparse_frontmatterrLXs[#%K D   e $ $!D   -55I !D  1y001445L 9==??Q&(( )D 5<(( fd # # ! K 555 &&((..t44 5 5D$C++JC',{{}}K $ $  5 55  s&B''A;D%$D%rEc|d}|sdSt|ts|g}tj}t }|D]|}t |}t||}| |rdS|r |dkrdS|r|dvrdS}dS)avReturn True when the skill is compatible with the current OS. Skills declare platform requirements via a top-level ``platforms`` list in their YAML frontmatter:: platforms: [macos] # macOS only platforms: [macos, linux] # macOS and Linux If the field is absent or empty the skill is compatible with **all** platforms (backward-compatible default). Termux note: on Termux/Android, ``sys.platform`` is ``"linux"`` on older Pythons but became ``"android"`` on Python 3.13+. Termux is a Linux userland riding on the Android kernel, so skills tagged ``linux`` are treated as compatible in Termux regardless of which ``sys.platform`` value Python reports. Individual Linux commands inside a skill may still misbehave (no systemd, BusyBox utils, no apt/dnf, etc.) but that is on the skill, not on platform gating. platformsTr)termuxandroidF) getr@listsysplatformr r$lowerrC PLATFORM_MAPr;)rErNcurrentrunning_in_termuxrT normalizedmappeds rskill_matches_platformr[s( ,,I t i & & K lG!   ]]((**0022 !!*j99   f % % 44  7!2!244  +@!@!@44 5r >s6dockerkanban_ENV_DETECT_CACHEenvc|tvr t|Sd}|dkr\tjdstjdrd}n ddlm}t |}n#t $rd}YnrwxYw|dkr$ dd lm}|}nV#t $rd}YnHwxYw|d kr>tj d ptj d }|t|<|S) zReturn True when the named runtime environment is currently active. Cached per process. Unknown env names return True (fail-open: never hide a skill because of a tag we don't understand). Tr^HERMES_KANBAN_TASKHERMES_KANBAN_BOARDr)_profile_has_kanban_toolsetFr]) is_containerr\z/run/s6z/package/admin/s6-overlay) r_osgetenvtools.kanban_toolsrdboolrBhermes_constantsrer&isdir)r`resultrdres r_detect_environmentrmsF   %% F h 9) * * bi8M.N.N FF JJJJJJ99;;<<       5 5 5 5 5 5!\^^FF   FFF   y)) RW]] '. . $c Ms$ A)) A87A8B B"!B"c|d}|sdSt|ts|g}|D]V}t|}|s8|t vrdSt|rdSWdS)uJReturn True when the skill is relevant to the current runtime environment. Skills may declare an ``environments`` list in their YAML frontmatter:: environments: [kanban] # only relevant when kanban is active environments: [s6] # only relevant inside the s6 Docker image environments: [docker] # only relevant inside any container If the field is absent or empty the skill is relevant in **all** environments (backward-compatible default). This is an OFFER-time filter: it controls whether a skill shows up in the skills index / autocomplete / slash-command list. It is intentionally NOT enforced by ``skill_view`` or ``--skills`` preloading — an explicit load is explicit consent, and load-bearing force-loads (e.g. the kanban dispatcher injecting ``--skills kanban-worker``) must always succeed regardless of how the offer surfaces filter the skill. A skill matches when ANY of its declared environments is currently active (OR semantics, mirroring ``platforms``). Unknown env tags fail open. environmentsTF)rQr@rRr$rUrC_KNOWN_ENVIRONMENTSrm)rEror`rYs rskill_matches_environmentrqs,??>22L t lD ) )&$~ XX^^%%++--    0 0 044 z * * 44  5r rTct}|stS t|d}nA#t $r4}t d||tcYd}~Sd}~wwxYwt|tstS| d}t|tstSddl m }|ptjdp |d }|r;| d pi |}|t|St| d S) aRead disabled skill names from config.yaml. Args: platform: Explicit platform name (e.g. ``"telegram"``). When *None*, resolves from ``HERMES_PLATFORM`` or ``HERMES_SESSION_PLATFORM`` env vars. Falls back to the global disabled list when no platform is determined. Reads the config file directly (no CLI config imports) to stay lightweight. utf-8encodingz"Could not read skill config %s: %sNskillsr)get_session_envHERMES_PLATFORMHERMES_SESSION_PLATFORMplatform_disableddisabled)r existssetr5 read_textrBloggerdebugr@rArQgateway.session_contextrwrfrg_normalize_string_set)rT config_pathrIe skills_cfgrwresolved_platformrzs rget_disabled_skill_namesrs"##K     uu ;00'0BBCC  9;JJJuu  fd # #uu H%%J j$ ' 'uu 777777 6 9& ' ' 6 ?4 5 5 <'^^,?@@FBKK     (():;; ;  !;!; < <z(_normalize_string_set..Bs9 = = =qc!ffllnn =CFFLLNN = = =r )r}r@r$)valuess rrr=s= ~uu &# = =F = = ==r _EXTERNAL_DIRS_CACHEc8tdS)u(Test hook — drop the in-process cache.N)rclearrr r_external_dirs_cache_clearrPs     r ct}|sgS |}t||jf}n#t $rd}YnwxYw|+t |}|t|S t| d}n#t$rgcYSwxYwt|tsgS|d}t|tsgS|d}|sg}|t|t |<|St|tr|g}t|tsgSddlm}|} t!} t%} g}|D]} t| } | s't(jt(j| } t1| }|s| |z }n|}|| kr|| vr|r+| |||t:d||t|t |<|S) u3Read ``skills.external_dirs`` from config.yaml and return validated paths. Each entry is expanded (``~`` and ``${VAR}``) and resolved to an absolute path. Only directories that actually exist are returned. Duplicates and paths that resolve to the local ``~/.hermes/skills/`` are silently skipped. Cached in-process, keyed on ``config.yaml`` mtime — the function is called once per skill during banner / tool-registry scans, and YAML parsing a non-trivial config dominates ``hermes`` cold-start time when the cache is absent. Nrsrtrv external_dirsr)get_hermes_homez0External skills dir does not exist, skipping: %s)r r|statr$ st_mtime_nsOSErrorrrQrRr5r~rBr@rArjrr resolver}rCrfr& expanduser expandvarsr is_absoluteis_diraddappendrr)rr cache_keycachedrIrraw_dirsrlr hermes_home local_skillsseenentryexpandedps rget_external_skills_dirsrUs"##K      !!&)+&6&68H%I  %)))44  << ;00'0BBCC   fd # # H%%J j$ ' ' ~~o..H   .26ll  + (C  : h % % 000000!/##K!##++--LeeD FPPE   ""  7%%bg&8&8&?&?@@ NN}} q))++AA A    99  88:: P HHQKKK MM!     LLKQ O O O O*.v,,Y' Ms#*A A A #B55 CCcftg}|t|S)uReturn all skill directories: local ``~/.hermes/skills/`` first, then external. The local dir is always first (and always included even if it doesn't exist yet — callers handle that). External dirs follow in config order. )r extendr)dirss rget_all_skills_dirsrs0    DKK(**+++ Kr cd|d}t|tsi}|dpi}t|tsi}|dg|dg|dg|dgdS)z>Extract conditional activation fields from parsed frontmatter.metadatahermesfallback_for_toolsetsrequires_toolsetsfallback_for_toolsrequires_tools)rrrr)rQr@rA)rErrs rextract_skill_conditionsrsz**H h % % \\( # # )rF fd # #!',CR!H!H#ZZ(;R@@$jj)=rBB **%5r::   r c|d}t|tsgS|d}t|tsgS|d}|sgSt|tr|g}t|tsgSg}t }|D]3}t|tst |dd}|r||vrUt |dd}|s||d} |d} | | | d<|d } t| t r,| r| | d <n|| d <|||| 5|S) aExtract config variable declarations from parsed frontmatter. Skills declare config.yaml settings they need via:: metadata: hermes: config: - key: wiki.path description: Path to the LLM Wiki knowledge base directory default: "~/wiki" prompt: Wiki directory path Returns a list of dicts with keys: ``key``, ``description``, ``default``, ``prompt``. Invalid or incomplete entries are silently skipped. rrconfigrK description)rKrdefaultNprompt) rQr@rArRr}r$rCrr) rErrrawrlritemrKdescrr prompt_texts rextract_skill_config_varsrs z**H h % % \\( # #F fd # # **X  C  #te c4  #%FD$%%  $((5"%%&&,,.. cTkk 488M2..//5577  ! ! ((9%%  &E) hhx(( k3 ' ' #K,=,=,?,? #)//11E(OO"E(O   e Mr crg}t}t}tD]}|st |dD]} |d}t |\}}n#t$rY8wxYw|dp |j j }t||vrot|st|} | D]N} | d|vrBt|| d<|| || dO |S)aYScan all enabled skills and collect their config variable declarations. Walks every skills directory, parses each SKILL.md frontmatter, and returns a deduplicated list of config var dicts. Each dict also includes a ``skill`` key with the skill name for attribution. Disabled and platform-incompatible skills are excluded. zSKILL.mdrsrtnamerKskill)r}rrriter_skill_index_filesr~rLrBrQparentrr$r[rrr) all_vars seen_keysr{ skills_dir skill_filerrE_ skill_name config_varsvars rdiscover_all_skill_config_varsrsi&(HUUI'))H)++..   ""  0ZHH . .J  **G*<<!23!7!7 QQ    %00JJ4E4JJ:(**)+66 3K@@K" . .u:Y..#&z??CLOOC(((MM#e*---  . .( Os(B B Bz skills.configr dotted_keyc|d}|}|D]&}t|tr ||vr ||}$dS|S)zPWalk a nested dict following a dotted key. Returns None if any part is missing..N)rDr@rA)rrr!rWrs r_resolve_dotpathr5sZ   S ! !EG gt $ $ dmGG44 Nr rczt}i}|rL t|d}t |t r|}n#t $rYnwxYwi}|D]}|d}td|}t||}|)t |tr*| s| dd}t |trDd|vsd |vr`` in config.yaml. Returns a dict mapping **logical** keys (as declared by skills) to their current values (or the declared default if the key isn't set). Path values are expanded via ``os.path.expanduser``. rsrtrKrNrr~z${)r r|r5r~r@rArBSKILL_CONFIG_PREFIXrr$rCrQrfr&rr) rrrrIresolvedr logical_key storage_keyr+s rresolve_skill_config_valuesrAsR"##KF {44g4FFGGF&$''     D  "H & &%j ,<<{<<  55 =Zs33=EKKMM=GGIr**E eS ! ! Bse||tu}}G&&rw'9'9%'@'@AAE % Os:A!! A.-A.c|dd}|sdSt|d}t|dkr |dddzS|S)z8Extract a truncated description from parsed frontmatter.rrz'"<N9z...)rQr$rClen)rEraw_descrs rextract_skill_descriptionrjsn}b11H r x==   & &u - -D 4yy2~~CRCy5  Kr rfilenamec#Kg}tjdD]@\}}}d|D|dd<||vr%|t||z At |fdD]}|VdS)zWalk skills_dir yielding sorted paths matching *filename*. Excludes Hermes metadata, VCS, virtualenv/dependency, and cache directories so dependencies cannot register nested skills. T) followlinksc$g|] }|tv |Srr)rds r z*iter_skill_index_files..s#CCCa/B&B&B1&B&B&Br NcHt|Sr)r$ relative_to)rrs rz(iter_skill_index_files..sc!-- 2K2K.L.Lr )rK)rfwalkrrsorted)rrmatchesrootrfilesr&s` rrrxs GWZTBBB22dECCdCCCQQQ u   NN4::0 1 1 1w$L$L$L$LMMM r z^[a-zA-Z0-9_-]+$rcXd|vrd|fSt|ddS)z~Split ``'namespace:skill-name'`` into ``(namespace, bare_name)``. Returns ``(None, name)`` when there is no ``':'``. r9Nr:)tuplerD)rs rparse_qualified_namers3  $Tz C## $ $$r candidatecX|sdStt|S)zDCheck whether *candidate* is a valid namespace (``[a-zA-Z0-9_-]+``).F)ri _NAMESPACE_REmatch)rs ris_valid_namespacers+ u  ##I.. / //r r)rN)7__doc__loggingrfr<rSr#rtypingrrrrrr rjr r r getLogger__name__rrV frozensetrrir'r2r$r5rLr[rpr___annotations__rmrqrrrintrrrrrrrrrrrcompilerrrrr rrs 8888888888888888GGGGGGGGGG  8 $ $    i(>D>>>>(  "s " " " "$"s"uT#s(^S-@'A""""P)S#X)4))))l i : : :;;%'4T ?'''+S+T++++\$4S>$d$$$$T'='=sTz'=SX'='='='=T>SX>>>> ;=d5c?DJ67<<<!!!! S$t*SSSSlT$Z$sCx.T#t)_(84S>8d4S>>R8888v$T#s(^(<$$$$T& T#s(^     #d38n%# #s(^####R4S>c t s    " .// %s%uXc]C-?'@%%%%0(3-0D000000r