`gjazUdZddlZddlZddlZddlZddlmZddlmZm Z m Z m Z m Z m Z ddlmZmZmZej$eZdddd Zed Zed Zd efd Zd efdZdadefdZded e e eefeffdZded efdZ de eefd efdZ!ehdZ"iZ#e eefe$d<ded efdZ%de eefd efdZ&iZ'e e ee(e(fe eeffe$d<d;dZ)d e eeffdZ*dd9e ed efd:Z?y)=aLightweight 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_cache) references templatesassetsscriptsreturnc |j}t d|Dxs t |S#t$r$ddlm}|t |j}YKwxYw)axTrue if *path* should be skipped by active skill scanners. Use this on every ``SKILL.md`` path produced by direct ``rglob`` scans to prune dependency, virtualenv, VCS, cache, and progressive-disclosure support-package paths. Centralising the check here keeps every skill-scanning site in sync with the shared exclusion set. Accepts a Path or string. r)PurePathc3,K|] }|tvywN)EXCLUDED_SKILL_DIRS).0parts D/root/.hermes/venv/lib/python3.12/site-packages/agent/skill_utils.py z)is_excluded_skill_path..Ds=tt**=s)partsAttributeErrorpathlibrstranyis_skill_support_path)pathr#rs r!is_excluded_skill_pathr*5s^*  =u= = AV B *$T#))*s -*AAct|tr|ntt|}|j}t |ddD]3\}}|t vs|dk(rt|d|}|dz j s3yy)aTrue if *path* is under a support dir of an actual skill root. ``references/``, ``templates/``, ``assets/``, and ``scripts/`` are progressive-disclosure support areas when they sit directly inside a skill directory containing ``SKILL.md``. They are not active discovery roots for standalone skills. A preserved package such as ``some-skill/references/old-skill-package/SKILL.md`` is documentation data unless the caller explicitly loads it via ``file_path``. Legitimate categories or skill names such as ``skills/scripts/foo`` remain discoverable because their ``scripts`` component is not directly under a directory that contains ``SKILL.md``. NrSKILL.mdTF) isinstancerr&r# enumerateSKILL_SUPPORT_DIRSexists)r)path_objr#idxr skill_roots r!r(r(Is"$-t4D ?H NNEuSbz* T ) )SAX 5#;'  # + + -  contentct.ddltddxs jdtffd }|at|S)z7Parse YAML with lazy import and CSafeLoader preference.Nr CSafeLoadervaluec*j|S)N)Loader)load)r9loaderyamls r!_loadzyaml_load.._loadqs99U692 2r5) _yaml_load_fnr>getattr SafeLoaderr&)r6r?r=r>s @@r! yaml_loadrCisC}d3Ft 3 3  !!r5ci}|jdr|dd}|}|jds||fStjd|dd}|s||fS|d|jdz}||j dzd} t |}t |tr|}||fS#t$re|jjdD]=}d|vr|jdd\}}|j||j<?Y||fSwxYw) uParse 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. A single leading UTF-8 BOM (U+FEFF) is stripped before parsing. Windows GUI editors (Notepad, PowerShell ``>``) prepend one when saving a SKILL.md as UTF-8, and ``read_text(encoding="utf-8")`` preserves it (only ``utf-8-sig`` strips it). Left in place, the BOM defeats the ``---`` fence check below and the whole frontmatter is silently discarded — name, description, ``platforms`` gating, env-var setup, and conditional activation all vanish. See CONTRIBUTING.md "File encoding". Returns: (frontmatter_dict, remaining_body) uNz---z \n---\s*\n :) startswithresearchstartendrCr.dict Exceptionstripsplit) r6 frontmatterbody end_match yaml_contentparsedlinekeyr9s r!parse_frontmatterrY{s6"#%K(#!"+ D   e $D   -5I D  1y0145L 9==?Q&( )D 5<( fd # K   5 &&(..t4 5D$C+JC',{{}K $  5  5s<BA(D  D  platformsc6|syt|ts|g}tj}t }|D]d}t |j j}tj||}|j|ry|r|dk(ry|s_|dvsdyy)z?Return True when *platforms* is compatible with the current OS.Tr)termuxandroidF) r.listsysplatformr r&lowerrP PLATFORM_MAPgetrI)rZcurrentrunning_in_termuxr` normalizedmappeds r!skill_matches_platform_listrhs  i &K llG!  ]((*002 !!*j9   f % 7!2 +@!@  r5rRc6t|jdS)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. rZ)rhrc)rRs r!skill_matches_platformrjs( '{{'C DDr5>s6dockerkanban_ENV_DETECT_CACHEenvc|tvr t|Sd}|dk(rEtjdstjdrd}nq ddlm}t |}nY|dk(r dd lm}|}nE|d k(r@tjjd xstjjd }|t|<|S#t $rd}YwxYw#t $rd}Y)wxYw) 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). TrmHERMES_KANBAN_TASKHERMES_KANBAN_BOARDr)_profile_has_kanban_toolsetFrl) is_containerrkz/run/s6z/package/admin/s6-overlay) rnosgetenvtools.kanban_toolsrsboolrOhermes_constantsrtr)isdir)roresultrsrts r!_detect_environmentr|s   %% F h 99) *bii8M.NF J9;<   5!^F  y) RWW]] '. $c M'   F s$C$ C CC C! C!c|jd}|syt|ts|g}|D]C}t|j j }|s-|t vryt|sCyy)uRReturn 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. a dispatcher pinning a task to a specialist skill via ``--skills``) 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)rcr.r^r&rarP_KNOWN_ENVIRONMENTSr|)rRr~rorfs r!skill_matches_environmentrss,??>2L  lD )$~ X^^%++-   0 0 z * r5_RAW_CONFIG_CACHEc,tjy)u/Test hook — drop the shared raw config cache.N)rclearr5r!_raw_config_cache_clearrIsr5ct}|jsiS |j}t||j|j f}|tj|}||S t|jd}t|tsiS|tj!|t|<|S#t $rd}YwwxYw#t$r#}tjd||icYd}~Sd}~wwxYw)aRead config.yaml with a shared mtime+size keyed cache. This module intentionally avoids importing ``hermes_cli.config`` on the skill prompt/build path. A tiny local cache gives the same repeated-read win without pulling the heavier CLI config stack into startup. Nutf-8encodingz"Could not read skill config %s: %s)r r1statr& st_mtime_nsst_sizeOSErrorrrcrC read_textrOloggerdebugr.rNr) config_pathr cache_keycachedrVes r!_load_raw_configrNs"#K     !%t'7'7F "&&y1  M;00'0BC fd # !'-)$ M'    9;J s/2B:,C : CC C7C2,C72C7r`czt}|s tS|jd}t|ts tSddlm}|xstjdxs|d}t|jd}|r4|jdxsij|}||t|zS|S)a Read 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. Returns the global disabled list, unioned with the platform-specific list when a platform is resolved (a globally-disabled skill stays disabled on every platform). Reads the config file directly (no CLI config imports) to stay lightweight. skillsr)get_session_envHERMES_PLATFORMHERMES_SESSION_PLATFORMdisabledplatform_disabled) rsetrcr.rNgateway.session_contextrrurv_normalize_string_set)r`rV skills_cfgrresolved_platformglobal_disabledrs r!get_disabled_skill_namesrqs F u H%J j$ 'u 7 6 99& ' 6 4 5 ,JNN:,FGO'^^,?@FBKK    ("%:;L%MM M r5c| tSt|tr|g}|Dchc]5}t|jst|j7c}Scc}wr)rr.r&rP)valuesvs r!rrsI ~u &#$* =qc!fllnCFLLN == =s A!A!_EXTERNAL_DIRS_CACHEc@tjty)u(Test hook — drop the in-process cache.N)rrrrr5r!_external_dirs_cache_clearrs r5cjt}|jsgS |j}t||jf}|"t j|}| t|St}|sgS|jd}t|tsgS|jd}|sg}|t|t |<|St|tr|g}t|tsgSddl m }|} tj} t!} g}|D]} t| j#} | st$j&j)t$j&j+| } t-| }|j/s| |z j}n|j}|| k(r|| vr|j1r#| j3||j5|t6j9d||t|t |<|S#t $rd}YwxYw)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. Nr external_dirsr)get_hermes_homez0External skills dir does not exist, skipping: %s)r r1rr&rrrrcr^rr.rNryrr resolverrPrur) expanduser expandvarsr is_absoluteis_diraddappendrr)rrrrrVrraw_dirsr{r hermes_home local_skillsseenentryexpandedps r!get_external_skills_dirsrs"#K     !&)+&68H8H%I %)))4  <   F  H%J j$ ' ~~o.H   .26l  + (C : h % 0!#K!#++-LeD FPE   " 77%%bgg&8&8&?@ N}}q))+A A   9  88: HHQK MM!  LLKQ O)P,*.v,Y' Mw  s'H## H21H2cNtg}|jt|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 r!get_all_skills_dirsrs$   DKK(*+ Kr5 identifierc|xsdj}|s|St|j}|js|j dS ddlm}t|j}|g} |jt|D]} t|j|cS t|jj|jS#t$r t}YwxYw#t$rY~wxYw#t$rYwxYw#t$rt j#d||cYSwxYw)aNormalize a skill identifier to a ``skill_view()``-safe relative path. Slash commands and cron jobs may store absolute paths to skills that live under ``~/.hermes/skills/`` (including via symlinks) or configured ``skills.external_dirs``. ``skill_view()`` rejects absolute names for security, so callers must translate trusted absolute paths to their relative form first. /r) skills_toolu~Skill identifier %r is an absolute path outside trusted skills roots — passing through unchanged (skill_view will reject it))rPrrrlstriptoolsr SKILLS_DIRrOr rrr& relative_to ValueErrorrrr)rraw_identifieridentifier_path _skills_tool primary_root trusted_rootsroots r!normalize_skill_lookup_namersM!&B--/N >*557O  & & ($$S))(5L334 "NM 578 22489 9 ?**,889M9M9OPQQ+ (%' (          N   sHC&3C?D05D&C<;C<? D  D  DD!EEct|tr|ntt|} |jj S#t t f$r!|jjcYSwxYwr)r.rr&rrr RuntimeErrorabsolute)r)r2s r!_resolve_for_skill_ownershiprGsc!$-t4D ?H0""$,,.. \ "0""$--//0sA-A65A6ct|}tD] }t|} |j|yy#t$rY/wxYw)aReturn True when ``path`` lives under a configured external skills dir. ``skills.external_dirs`` are externally owned: Hermes can discover and view their skills, and foreground user-directed tool calls may still edit them, but autonomous lifecycle maintenance must treat them as read-only. This helper centralizes the ownership boundary so curator/reporting/tool paths do not each need to re-interpret the config. TF)rrrr)r) candidater resolved_roots r!is_external_skill_pathrOsY-T2I(*4T:    ! !- 0     s: AAc$|jd}t|tsi}|jdxsi}t|tsi}|jdg|jdg|jdg|jdgdS)z>Extract conditional activation fields from parsed frontmatter.metadatahermesfallback_for_toolsetsrequires_toolsetsfallback_for_toolsrequires_tools)rrrr)rcr.rN)rRrrs r!extract_skill_conditionsrfsz*H h % \\( # )rF fd #!',CR!H#ZZ(;R@$jj)=rB **%5r:  r5c|jd}t|tsgS|jd}t|tsgS|jd}|sgSt|tr|g}t|tsgSg}t }|D]}t|tst |jddj }|r||vrDt |jddj }|sp||d} |jd} | | | d<|jd } t| t r$| j r| j | d <n|| d <|j||j| |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. rrconfigrXr description)rXrdefaultprompt) rcr.rNr^rr&rPrr) rRrrrawr{ritemrXdescrr prompt_texts r!extract_skill_config_varsrzss z*H h % \\( #F fd # **X C  #te c4  #%FD$% $((5"%&,,.cTk 488M2./557 ! ((9%  &E) hhx( k3 'K,=,=,?)//1E(O"E(O   e/0 Mr5cg}t}t}tD]}|jst |dD]} |j d}t |\}}|jdxs|jj}t||vr[t|sgt|} | D]=} | d|vs t|| d<|j| |j| d?|S#t$rYwxYw)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. r-rrnamerXskill)rrrriter_skill_index_filesrrYrOrcparentrr&rjrrr) all_vars seen_keysr skills_dir skill_filerrR_ skill_name config_varsvars r!discover_all_skill_config_varsrs&(HUI')H)+.   " 0ZH .J  **G*<!23!7 Q%0JJ4E4E4J4JJ:(*)+63K@K" .u:Y.#&z?CLOOC(MM#e*-  . ... O!  s C;; DDz skills.configr dotted_keycp|jd}|}|D]}t|tr ||vr||}y|S)zPWalk a nested dict following a dotted key. Returns None if any part is missing..N)rQr.rN)rrr#rdr s r!_resolve_dotpathrsI   S !EG gt $dmG  Nr5rc~t}i}|D]}|d}td|}t||}| t|tr"|j s|j 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``. rXrrr~z${) rSKILL_CONFIG_PREFIXrr.r&rPrcrur)rr)rrresolvedr logical_key storage_keyr9s r!resolve_skill_config_valuesrs F!H &%j ,-Q{m<  5 =Zs3EKKMGGIr*E eS !se|tu}GG&&rww'9'9%'@AE % & Or5c|jdd}|syt|jjd}t|dkDr|dddzS|S)z8Extract a truncated description from parsed frontmatter.rrz'"<N9z...)rcr&rPlen)rRraw_descrs r!extract_skill_descriptionr sV}b1H  x=   & &u -D 4y2~CRy5  Kr5rfilenamec#dKt|}g}tj|dD]c\}}}d|v}|Dcgc]}|tvr |r|tvs|c}|dd||vs5|j tj j||et|D]} t| ycc}ww)aWalk skills_dir yielding sorted paths matching *filename*. Excludes Hermes metadata, VCS, virtualenv/dependency, cache, and skill support directories. Support directories (references/templates/assets/ scripts) can contain arbitrary markdown and even archived package ``SKILL.md`` files, but they are progressive-disclosure data loaded through ``skill_view(..., file_path=...)`` rather than active skill roots. T) followlinksr-N) r&ruwalkrr0rr)joinsortedr) rr skills_dir_strmatchesrrfiles has_skill_mddr)s r!rrs_NGWW^F 9dE!U*  ++!a+=&=  Q u  NN277<<h7 8 9w4j s4B0B+ B0AB0z^[a-zA-Z0-9_-]+$rcHd|vrd|fSt|jddS)z~Split ``'namespace:skill-name'`` into ``(namespace, bare_name)``. Returns ``(None, name)`` when there is no ``':'``. rHNrE)tuplerQ)rs r!parse_qualified_namer;s+  $Tz C# $$r5rcD|syttj|S)zDCheck whether *candidate* is a valid namespace (``[a-zA-Z0-9_-]+``).F)rx _NAMESPACE_REmatch)rs r!is_valid_namespacerEs   ##I. //r5)rNr)@__doc__loggingrurJr_r%rtypingrrrrrr ryr r r getLogger__name__rrb frozensetrr0rxr*r(r@r&rCrYrhrjrrn__annotations__r|rrintrrrrrrrrrrrrrrrrrr rcompilerrrrr5r!r%sU 88GG   8 $    .OPD(4:  "s "$.s.uT#s(^S-@'A.h342ES#XE4EB :;%'4T ?'+S+T+\$4S>$d$TAC4c3m,d38n<=B $sCx. F#sTz#SX#L>SX> ;=d5c?DJ67< P$t*PfT$Z6C6C6r0$0D.$sCx.T#t)_(84S>8d4S>>R8v$T#s(^(<$T& T#s(^  d38n% #s(^B4S>cts6 ./ %s%uXc]C-?'@%0(3-0D0r5