(GjnZUdZddlZddlZddlZddlZddlmZddlmZm Z m Z m Z m Z m Z ddlmZmZmZejeZdddd Zed Zed Zd efd Zd efdZdadefdZded e e eefeffdZde eefd efdZ ehdZ!iZ"e eefe#d<ded efdZ$de eefd efdZ%iZ&e e ee'e'fe eeffe#d<d7dZ(d e eeffdZ)d8dedzd e efdZ*d e efdZ+iZ,e e ee'fe efe#d<d7d Z-d e efd!Z.d e efd"Z/d efd#Z0d efd$Z1de eefd e ee ffd%Z2de eefd e e eeffd&Z3d e e eeffd'Z4d(Z5d)e eefd*efd+Z6d,e e eefd e eeffd-Z7de eefd efd.Z8d/ed0efd1Z9ej:d2Z;d3ed e e eeffd4Zz)is_excluded_skill_path..Ds(==tt**======)partsAttributeErrorpathlibrstranyis_skill_support_path)pathr$rs r!is_excluded_skill_pathr+5s*  ***$$$$$$T##)* ==u=== = = AV BBs  -::c*t|tr|ntt|}|j}t |ddD]@\}}|t vs|dkrt|d|}|dz rdSAdS)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"$--Btt4D ??H NEuSbSz** T ) ) )SAXX 5#;'  # + + - - 44  5r#contentct,ddltddpjdtffd }|at|S)z7Parse YAML with lazy import and CSafeLoader preference.Nr CSafeLoadervaluec2|S)N)Loader)load)r9loaderyamls r!_loadzyaml_load.._loadqs99U6922 2r#) _yaml_load_fnr>getattr SafeLoaderr')r6r?r=r>s @@r! yaml_loadrCisl }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 :) startswithresearchstartendrCr/dict Exceptionstripsplit) r6 frontmatterbody end_match yaml_contentparsedlinekeyr9s r!parse_frontmatterrY{s[#%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%rRc|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'lowerrP PLATFORM_MAPrI)rRr[currentrunning_in_termuxra normalizedmappeds r!skill_matches_platformrhs( ,,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). TrkHERMES_KANBAN_TASKHERMES_KANBAN_BOARDr)_profile_has_kanban_toolsetFrj) is_containerriz/run/s6z/package/admin/s6-overlay) rlosgetenvtools.kanban_toolsrqboolrOhermes_constantsrrr*isdir)rmresultrqrrs r!_detect_environmentrzsF   %% 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)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)r^r/r_r'rbrP_KNOWN_ENVIRONMENTSrz)rRr|rmrfs r!skill_matches_environmentr~ s,??>22L t lD ) )&$~ XX^^%%++--    0 0 044 z * * 44  5r#_RAW_CONFIG_CACHEc8tdS)u/Test hook — drop the shared raw config cache.N)rclearr#r!_raw_config_cache_clearr9sr#cBt}|siS |}t||j|jf}n#t $rd}YnwxYw|t|}||S t| d}n5#t$r(}t d||icYd}~Sd}~wwxYwt|tsiS|#t|t|<|S)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 r2statr' st_mtime_nsst_sizeOSErrorrr^rC read_textrOloggerdebugr/rNr) config_pathr cache_keycachedrVes r!_load_raw_configr>sN"##K      !!%%t'7F  "&&y11  M;00'0BBCC  9;JJJ  fd # # !!!'-)$ Ms/0A A&%A& #B.. C 8CC C ract}|stS|d}t|tstSddlm}|ptjdp |d}t|d}|r>|dpi|}||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) rsetr^r/rNgateway.session_contextrrsrt_normalize_string_set)rarV skills_cfgrresolved_platformglobal_disabledrs r!get_disabled_skill_namesras  F uu H%%J j$ ' 'uu 777777 6 9& ' ' 6 ?4 5 5 ,JNN:,F,FGGON'^^,?@@FBKK     ("%:;L%M%MM M r#cj|tSt|tr|g}d|DS)Nch|]D}t|#t|ESr)r'rP)rvs r! z(_normalize_string_set..s9 = = =qc!ffllnn =CFFLLNN = = =r#)rr/r')valuess r!rrs= ~uu &# = =F = = ==r#_EXTERNAL_DIRS_CACHEcTttdS)u(Test hook — drop the in-process cache.N)rrrrr#r!_external_dirs_cache_clearrs&   r#cPt}|sgS |}t||jf}n#t $rd}YnwxYw|+t |}|t|St}|sgS|d}t|tsgS|d}|sg}|t|t |<|St|tr|g}t|tsgSddl m }|} t} t!} g}|D]} t| } | s't$jt$j| } t-| }|s| |z }n|}|| kr|| vr|r+| |||t6d||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. Nr external_dirsr)get_hermes_homez0External skills dir does not exist, skipping: %s)r r2rr'rrrr^r_rr/rNrwrr resolverrPrsr* expanduser expandvarsr is_absoluteis_diraddappendrr)rrrrrVrraw_dirsryr hermes_home local_skillsseenentryexpandedps r!get_external_skills_dirsrs"##K      !!&)+&6&68H%I  %)))44  <<    F  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 cftg}|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 r!get_all_skills_dirsrs0    DKK(**+++ Kr#c0t|tr|ntt|} |S#t t f$r)|cYSwxYwr)r/rr'rrr RuntimeErrorabsolute)r*r3s r!_resolve_for_skill_ownershiprs!$--Btt4D ??H0""$$,,... \ "000""$$--/////0s%A7BBct|}tD]9}t|} ||dS#t$rY6wxYwdS)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)rr relative_to ValueError)r* candidateroot resolved_roots r!is_external_skill_pathrsx-T22I(**4T::    ! !- 0 0 044    H  5sA AAcd|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)r^r/rN)rRrrs r!extract_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. rrconfigrX description)rXrdefaultNprompt) r^r/rNr_rr'rPrr) rRrrrawryritemrXdescrr prompt_texts r!extract_skill_config_varsr1s 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. r.rrnamerXskill)rrrriter_skill_index_filesrrYrOr^parentrr'rhrrr) all_vars seen_keysr skills_dir skill_filerrR_ skill_name config_varsvars r!discover_all_skill_config_varsrlsi&(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)rQr/rN)rrr$rdr s r!_resolve_dotpathrsZ   S ! !EG gt $ $ dmGG44 Nr#rct}i}|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``. rXrNrr~z${) rSKILL_CONFIG_PREFIXrr/r'rPr^rsr*rr)rrresolvedr logical_key storage_keyr9s r!resolve_skill_config_valuesrs  F!H & &%j ,<<{<<  55 =Zs33=EKKMM=GGIr**E eS ! ! Bse||tu}}G&&rw'9'9%'@'@AAE % Or#c|dd}|sdSt|d}t|dkr |dddzS|S)z8Extract a truncated description from parsed frontmatter.rrz'"<N9z...)r^r'rPlen)rRraw_descrs r!extract_skill_descriptionrsn}b11H r x==   & &u - -D 4yy2~~CRCy5  Kr#rfilenamec#Kg}tjdD]F\}}}d|vfd|D|dd<||vr%|t||z Gt |fdD]}|VdS)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.c<g|]}|tvr r |tv|Sr)rr1)rd has_skill_mds r! z*iter_skill_index_files..sE   +++!,&'+=&=&= '>&=&=r#NcHt|Sr)r'r)rrs r!z(iter_skill_index_files..sc!-- 2K2K.L.Lr#)rX)rswalkrrsorted)rrmatchesrrfilesr*rs` @r!rrsGWZTBBB 2 2dE!U*        QQQ 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 ``':'``. rGNrH)tuplerQ)rs r!parse_qualified_namer s3  $Tz C## $ $$r#rcX|sdStt|S)zDCheck whether *candidate* is a valid namespace (``[a-zA-Z0-9_-]+``).F)rv _NAMESPACE_REmatch)rs r!is_valid_namespacers+ u  ##I.. / //r#)rNr)>__doc__loggingrsrJr`r&rtypingrrrrrr rwr r r getLogger__name__rrc frozensetrr1rvr+r)r@r'rCrYrhr}rl__annotations__rzr~rintrrrrrrrrrrrrrrrrrrcompilerr rrr#r!rsV 8888888888888888GGGGGGGGGG  8 $ $    i.YOPPD(4:  "s " " " "$"s"uT#s(^S-@'A""""P)S#X)4))))l i : : :;;%'4T ?'''+S+T++++\$4S>$d$$$$TAC4c3m,d38n<=BBB $sCx.    F##sTz#SX####L>SX>>>> ;=d5c?DJ67<<< P$t*PPPPfT$Z0$0000D.$sCx.T#t)_(84S>8d4S>>R8888v$T#s(^(<$$$$T& T#s(^     d38n% #s(^B4S>cts4 .// %s%uXc]C-?'@%%%%0(3-0D000000r#