.cj|UdZddlZddlZddlZddlZddlmZddlmZm Z m Z m Z m Z m Z ddlmZmZmZejeZdddd 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*d?dedzd e efdZ+d e efd Z,iZ-e e ee(fe efe$d!<d>d"Z.d e efd#Z/d e efd$Z0d%ed efd&Z1d efd'Z2d efd(Z3de eefd e ee ffd)Z4de eefd e e eeffd*Z5d e e eeffd+Z6d,Z7d-e eefd.efd/Z8d0e e eefd e eeffd1Z9d2Z:de eefd efd3Z;de eefd efd4Zej?d9Z@d:ed e e eeffd;ZAdz)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#ci}|dr |dd}|}|ds||fStjd|dd}|s||fS|d|dz}||dzd} t |}t |tr|}n#t$rt| dD]I}d|vr| dd\}}| || <JYnwxYw||fS) 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{s"#%K(##!""+ D   e $ $!D   -55I !D  1y001445L 9==??Q&(( )D 5<(( fd # # ! K 555 &&((..t44 5 5D$C++JC',{{}}K $ $  5 55  s&CA;EE platformscp|sdSt|ts|g}tj}t }|D]|}t |}t ||}| |rdS|r |dkrdS|r|dvrdS}dS)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 t i & & K lG!   ]]((**0022 !!*j99   f % % 44  7!2!244  +@!@!@44 5r#rRcFt|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. rZ)rhrc)rRs r!skill_matches_platformrjs( '{{'C'C D DDr#>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). 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|sF   %% 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)rcr/r^r'rarP_KNOWN_ENVIRONMENTSr|)rRr~rorfs r!skill_matches_environmentrs,??>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_clearrIsr#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_sizeOSErrorrrcrC read_textrOloggerdebugr/rNr) config_pathr cache_keycachedrVes r!_load_raw_configrNsN"##K      !!%%t'7F  "&&y11  M;00'0BBCC  9;JJJ  fd # # !!!'-)$ Ms/0A A&%A& #B.. C 8CC C r`ct}|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) rsetrcr/rNgateway.session_contextrrurv_normalize_string_set)r`rV skills_cfgrresolved_platformglobal_disabledrs r!get_disabled_skill_namesrqs  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'rrrrcr^rr/rNryrr resolverrPrur* expanduser expandvarsr is_absoluteis_diraddappendrr)rrrrrVrraw_dirsr{r 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# identifierc|pd}|s|St|}|s|dS ddlm}t|j}n#t$rt}YnwxYw|g} | tn#t$rYnwxYw|D]6} t| |cS#t$rY3wxYw t| |S#t$r t 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_namers!&B--//N >**5577O  & & ( (*$$S)))(555555L344 (((%'' ("NM 5778888       2248899 9 9 9    H ?**,,889M9M9O9OPPQQQ   N     sI&BBB#!C CC!C>> D  D AE'E?>E?c0t|tr|ntt|} |S#t t f$r)|cYSwxYwr)r/rr'rrr RuntimeErrorabsolute)r*r3s r!_resolve_for_skill_ownershiprGs!$--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)rrrr)r* candidater resolved_roots r!is_external_skill_pathrOsx-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)rcr/rN)rRrrs r!extract_skill_conditionsrfsz**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. rrconfigrXr description)rXrdefaultNprompt) rcr/rNr^rr'rPrr) rRrrrawr{ritemrXdescrr prompt_texts r!extract_skill_config_varsrzs 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_filesrrYrOrcparentrr'rjrrr) all_vars seen_keysr skills_dir skill_filerrR_ skill_name config_varsvars r!discover_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)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'rPrcrur*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}|r4t|dndS)z@Normalize a skill's description field for comparison/truncation.rrz'")rcr'rP)rRraw_descs r!_normalize_skill_descriptionr sE}b11H19 A3x==   & &u - - -rAr#ct|}|sdSt|tkr|dtdz dzS|S)zCExtract a system-prompt-length description from parsed frontmatter.rNrFz...r lenSKILL_PROMPT_DESC_LIMITrRrs r!extract_skill_descriptionrsO ' 4 4D r 4yy***0,q001E99 Kr#cPt|}t|tkS)zMTrue when the description will be truncated in the system prompt skill index.r rs r!)is_skill_description_truncated_for_promptr!s! ' 4 4D t99. ..r#rfilenamec#JKt|}g}tj|dD]T\}}}d|vfd|D|dd<||vr3|tj||Ut |D]}t|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..7sE   +++!,&'+=&=&= '>&=&=r#N)r'ruwalkrr*joinsortedr) rrskills_dir_strmatchesrrfilesr*rs @r!rr*s__NGW^FFF 9 9dE!U*        QQQ u   NN27<<h77 8 8 8w4jjr#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 ``':'``. rHNrE)tuplerQ)rs r!parse_qualified_namer!Hs3  $Tz C## $ $$r#rcX|sdStt|S)zDCheck whether *candidate* is a valid namespace (``[a-zA-Z0-9_-]+``).F)rx _NAMESPACE_REmatch)rs r!is_valid_namespacer%Rs+ u  ##I.. / //r#)rNr)C__doc__loggingrurJr_r&rtypingrrrrrr ryr r r getLogger__name__rrb frozensetrr1rxr+r)r@r'rCrYrhrjrrn__annotations__r|rrintrrrrrrrrrrrrrrrrrr r rrrcompiler#r!r%rr#r!r/s 8888888888888888GGGGGGGGGG  8 $ $    i.YOPPD(4:  "s " " " "$.s.uT#s(^S-@'A....h342ES#XE4EEEEB i : : :;;%'4T ?'''+S+T++++\$4S>$d$$$$TAC4c3m,d38n<=BBB $sCx.    F##sTz#SX####L>SX>>>> ;=d5c?DJ67<<< P$t*PPPPfT$Z6C6C6666r0$0000D.$sCx.T#t)_(84S>8d4S>>R8888v$T#s(^(<$$$$T& T#s(^     d38n% #s(^@Bd38nBBBBB 4S>c/4S>/d////ts6 .// %s%uXc]C-?'@%%%%0(3-0D000000r#