PmjBUdZddlZddlZddlZddlZddlmZddlmZm Z m Z m Z m Z m Z ddlmZmZmZejeZdddd Zed Zed Zd Zd ZdZdZdede efdZdedefdZ dede efdZ!ddde edefdZ"ddde edefdZ#da$defdZ%dede e eefeffdZ&dedefdZ'de eefdefdZ(ehd Z)iZ*e eefe+d!<d"edefd#Z,de eefdefd$Z-iZ.e e ee/e/fe eeffe+d%<dGd&Z0de eeffd'Z1dHd(edzde efd)Z2de efd*Z3iZ4e e ee/fe efe+d+<dGd,Z5de efd-Z6de efd.Z7d/edefd0Z8defd1Z9defd2Z:de eefde ee ffd3Z;de eefde e eeffd4Zd7e eefd8efd9Z?d:e e eefde eeffd;Z@dZCde eefdefd?ZDded@efdAZEejFdBZGdCede e eeffdDZHdEe edefdFZIdS)IaLightweight 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 templatesassetsscripts_orgz .active_orgz.org-provenance.jsonz.org-baseline.json skills_dirreturnc |tz tz }|sdS|d}|pdS#t $rYdSwxYw)zBThe org id whose mirror may resolve, or None (no org skills load).Nutf-8encoding)ORG_MIRROR_DIR_NAMEORG_ACTIVE_MARKERexists read_textstripOSError)rmarkervals 7/home/thesage/.hermes/hermes-agent/agent/skill_utils.pyread_active_org_idr)Fs{114EE}} 4006688{d tts&A+A A$#A$c0 t|t|}n#ttf$rYdSwxYwt |jo|jdtkS)z6True when *path* is inside the org mirror (``_org/``).Fr)rresolve relative_tor% ValueErrorboolpartsr pathrrels r(is_org_mirror_pathr3Rs4jj  ""..tJ/?/?/G/G/I/IJJ Z uu  ?? Bsy|/BBBAAA+*A+cV t|t|}n#ttf$rYdSwxYwt |jdkr#|jdtkr |jdSdS)z@The ```` segment for a path under ``_org//...``.Nr)rr+r,r%r-lenr/r r0s r(org_id_of_pathr9[s4jj  ""..tJ/?/?/G/G/I/IJJ Z tt 39~~sy|/BBBy| 4r4rootr;c |j}n3#t$r&ddlm}|t |j}YnwxYwt d|Dpt ||S)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|] }|tvVdSN)EXCLUDED_SKILL_DIRS).0parts r( z)is_excluded_skill_path..us(==tt**======r:)r/AttributeErrorpathlibr=stranyis_skill_support_path)r1r;r/r=s r(is_excluded_skill_pathrJfs*  ***$$$$$$T##)* ==u=== = = AV 4BBBs  -::c`t|tr|ntt|}|j}t |ddD][\}}|t vs|dkrt|d|}||s||z }|dz rdS\dS)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) isinstancerrGr/ enumerateSKILL_SUPPORT_DIRS is_absoluter")r1r;path_objr/idxrB skill_roots r(rIrIzs"$--Btt4D ??H NEuSbSz** T ) ) )SAXX 5#;'  H$8$8$:$:  *J  # + + - - 44  5rDcontentct,ddltddpjdtffd }|at|S)z7Parse YAML with lazy import and CSafeLoader preference.Nr CSafeLoadervaluec2|S)N)Loader)load)rXloaderyamls r(_loadzyaml_load.._loads99U6922 2rD) _yaml_load_fnr]getattr SafeLoaderrG)rUr^r\r]s @@r( yaml_loadrbsl }d33Ft 3 3 3 3 3 3 3 3  ! !!rDci}|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) ur7Nz---z \n---\s*\n :) startswithresearchstartendrbrNdict Exceptionr$split) rU frontmatterbody end_match yaml_contentparsedlinekeyrXs r(parse_frontmatterrvs"#%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) rNlistsysplatformr rGlowerr$ PLATFORM_MAPgetrg)rwcurrentrunning_in_termuxr} normalizedmappeds r(skill_matches_platform_listrs t i & & K lG!   ]]((**0022 !!*j99   f % % 44  7!2!244  +@!@!@44 5rDrocFt|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. rw)rr)ros r(skill_matches_platformrs( '{{'C'C D DDrD>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). TrHERMES_KANBAN_TASKHERMES_KANBAN_BOARDr)_profile_has_kanban_toolsetFr) is_containerrz/run/s6z/package/admin/s6-overlay) rosgetenvtools.kanban_toolsrr.rmhermes_constantsrr1isdir)rresultrrs 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)rrNr{rGr~r$_KNOWN_ENVIRONMENTSr)rorrrs r(skill_matches_environmentrOs,??>22L t lD ) )&$~ XX^^%%++--    0 0 044 z * * 44  5rD_RAW_CONFIG_CACHEc8tdS)u/Test hook — drop the shared raw config cache.N)rclearrDr(_raw_config_cache_clearr|srDcBt}|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. Nrrz"Could not read skill config %s: %s)r r"statrG st_mtime_nsst_sizer%rrrbr#rmloggerdebugrNrlr) config_pathr cache_keycachedrses r(_load_raw_configrsN"##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) rsetrrNrlgateway.session_contextrrr_normalize_string_set)r}rs skills_cfgrresolved_platformglobal_disabledrs r(get_disabled_skill_namesrs  F uu H%%J j$ ' 'uu 777777 6 9& ' ' 6 ?4 5 5 ,JNN:,F,FGGON'^^,?@@FBKK     ("%:;L%M%MM M rDcj|tSt|tr|g}d|DS)Nch|]D}t|#t|ESr)rGr$)rAvs r( z(_normalize_string_set..s9 = = =qc!ffllnn =CFFLLNN = = =rD)rrNrG)valuess r(rrs= ~uu &# = =F = = ==rD_EXTERNAL_DIRS_CACHEcTttdS)u(Test hook — drop the in-process cache.N)rrrrrDr(_external_dirs_cache_clearrs&   rDcPt}|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 r"rrGrr%rrr{rrNrlrrr r+rr$rr1 expanduser expandvarsrrQis_diraddappendrr)rrrrrsrraw_dirsrr 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_dirsr6s0    DKK(**+++ KrD 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))r$rrrQlstriptoolsr SKILLS_DIRrmr rrrGr,r-r+rr)rraw_identifieridentifier_path _skills_tool primary_root trusted_rootsr;s r(normalize_skill_lookup_namerAs!&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?)rNrrGrr+r% RuntimeErrorabsolute)r1rRs r(_resolve_for_skill_ownershiprzs!$--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)rrr,r-)r1 candidater; 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)rrNrl)rorrs r(extract_skill_conditionsrsz**H h % % \\( # # )rF fd # #!',CR!H!H#ZZ(;R@@$jj)=rBB **%5r::   rDc|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. rrconfigrur description)rurdefaultNprompt) rrNrlr{rrGr$rr) rorrrawrritemrudescrr prompt_texts r(extract_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 MrDcrg}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. rMrrnameruskill)rrrriter_skill_index_filesr#rvrmrparentrrGrrrr) all_vars seen_keysrr skill_filerro_ skill_name config_varsvars r(discover_all_skill_config_varsr si&(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)rnrNrl)rr r/rrBs r(_resolve_dotpathrsZ   S ! !EG gt $ $ dmGG44 NrDr ct}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``. rurNrr~z${) rSKILL_CONFIG_PREFIXrrNrGr$rrr1rr)r rresolvedr  logical_key storage_keyrXs r(resolve_skill_config_valuesr!s  F!H & &%j ,<<{<<  55 =Zs33=EKKMM=GGIr**E eS ! ! Bse||tu}}G&&rw'9'9%'@'@AAE % OrD<c|dd}|r4t|dndS)z@Normalize a skill's description field for comparison/truncation.rrz'")rrGr$)roraw_descs r(_normalize_skill_descriptionrDsE}b11H19 A3x==   & &u - - -rArDct|}|sdSt|tkr|dtdz dzS|S)zCExtract a system-prompt-length description from parsed frontmatter.rNrdz...rr8SKILL_PROMPT_DESC_LIMITrors r(extract_skill_descriptionrJsO ' 4 4D r 4yy***0,q001E99 KrDcPt|}t|tkS)zMTrue when the description will be truncated in the system prompt skill index.rrs r()is_skill_description_truncated_for_promptr!Ts! ' 4 4D t99. ..rDfilenamec#> Kt|}t| tj|t }g}tj|dD]\}}}d|v ||kr&t |vr |t n||kr fd|D|dd< fd|D|dd<||vr3|tj||t|D]}t|VdS)uWalk 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. M2 org mirrors (``_org/``): TOKEN-GATED resolution. Only the active org's subdir (per the sync-client-written ``.active_org`` marker) is walked; every other ``_org//`` (stale mirror from a previous org, or no marker at all) is pruned — leave an org and its skills stop resolving, without any manual cleanup. T) followlinksrMNc g|] }|k| Srr)rAd active_orgs r( z*iter_skill_index_files..vs:::Q!z//q///rDc<g|]}|tvr r |tv|Sr)r@rP)rAr& has_skill_mds r(r(z*iter_skill_index_files..wsE   +++!,&'+=&=&= '>&=&=rD) rGr)rr1joinr walkremoversortedr) rr"skills_dir_strorg_rootmatchesr;rfilesr1r'r*s @@r(rr]s]__N#J//Jw||N,?@@HGW^FFF99dE!U* > ! !&9T&A&AjFX KK+ , , , , X  ::::$:::DG       QQQ u   NN27<<h77 8 8 8w4jjrDz^[a-zA-Z0-9_-]+$rcXd|vrd|fSt|ddS)z~Split ``'namespace:skill-name'`` into ``(namespace, bare_name)``. Returns ``(None, name)`` when there is no ``':'``. rfNr7)tuplern)rs r(parse_qualified_namer5s3  $Tz C## $ $$rDrcX|sdStt|S)zDCheck whether *candidate* is a valid namespace (``[a-zA-Z0-9_-]+``).F)r. _NAMESPACE_REmatch)rs r(is_valid_namespacer9s+ u  ##I.. / //rD)rNr?)J__doc__loggingrrhr|rFrtypingrrrrrr rr r r getLogger__name__rr frozensetr@rPr r!ORG_PROVENANCE_FILEORG_BASELINE_FILErGr)r.r3r9rJrIr_rbrvrrrr__annotations__rrrintrrrrrrrrrrrrrr rrrrrrr!rcompiler7r5r9rrDr(rEs 8888888888888888GGGGGGGGGG  8 $ $    i.YOPP!,) 4 HSM    CC$CCCCThsm<@(4.D(;?$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////#t#s####P .// %s%uXc]C-?'@%%%%0(3-0D000000rD