(GjUdZddlmZddlZddlZddlZddlZddlmZddl m Z m Z ddl m Z ddl mZmZmZmZmZmZddlmZdd lmZmZejeZdZ ddlZn#e$rdZ ddlZn #e$rYnwxYwYnwxYwd Zd Z d Z!ee e!hZ"d hZ#de$d<dZdZ%d[dZ&d[dZ'edZ(d[dZ)d\dZ*d]dZ+d^d"Z,d_d$Z-d`d%Z.d`d&Z/dad'Z0d[d(Z1d`d)Z2dbd,Z3dcd-Z4dcd.Z5ddd0Z6ddd1Z7ded4Z8dZd5Z9dZd6Z:dZd7Z;dfd8Zdjd=Z?dkd?Z@dldAZAdmdBZBdcdCZCdDdEdndGZDdcdHZEdcdIZFdcdJZGdcdKZHdodMZIdpdOZJdcdPZKdqdRZLdqdSZMdrdTZNdrdUZOdsdWZPdfdXZQdsdYZRdS)taSkill usage telemetry + provenance tracking for the Curator feature. Tracks per-skill usage metadata in a sidecar JSON file (~/.hermes/skills/.usage.json) keyed by skill name. Counters are bumped by the existing skill tools (skill_view, skill_manage); the curator orchestrator reads the derived activity timestamp to decide lifecycle transitions. Design notes: - Sidecar, not frontmatter. Keeps operational telemetry out of user-authored SKILL.md content and avoids conflict pressure for bundled/hub skills. - Atomic writes via tempfile + os.replace (same pattern as .bundled_manifest). - All counter bumps are best-effort: failures log at DEBUG and return silently. A broken sidecar never breaks the underlying tool call. - Provenance filter: curator-managed skills are explicitly marked when created through skill_manage. Bundled / hub-installed skills stay off-limits, and manually authored skills are not inferred from location. Lifecycle states: active -> default stale -> unused > stale_after_days (config) archived -> unused > archive_after_days (config); moved to .archive/ pinned -> opt-out from auto transitions (boolean flag, orthogonal to state) ) annotationsN)contextmanager)datetimetimezone)Path)AnyDictListOptionalSetTupleget_hermes_home)is_excluded_skill_pathis_external_skill_pathactivestalearchivedplanSet[str]PROTECTED_BUILTIN_SKILLS skill_namestrreturnboolc|tvS)a:Whether *skill_name* is a load-bearing built-in the curator never touches. Protected built-ins are exempt from archival and consolidation on every path: the automatic state-transition walk, the LLM consolidation pass (they are dropped from the candidate list), and direct ``archive_skill`` calls. )rrs 7/home/rurouni/.hermes/hermes-agent/tools/skill_usage.pyis_protected_builtinrGs 1 11rc$tdz S)Nskillsrr r _skills_dirr$Qs   x ''r c$tdz S)Nz .usage.jsonr$r#r r _usage_filer'Us === ((r c#XKtd}|jddt t dVdSt rH|r|jdkr| ddt|t rd nd d} tr t j |tj nG| dt j|t jd dVtr8 t j |tjn~#t$t&f$rYnkwxYwt r` | dt j|t jd n#t$t&f$rYnwxYw|dS#tr8 t j |tjn~#t$t&f$rYnkwxYwt r` | dt j|t jd n#t$t&f$rYnwxYw|wxYw) z@Serialize .usage.json read-modify-write cycles across processes.z .json.lockTparentsexist_okNr utf-8encodingzr+za+)r' with_suffixparentmkdirfcntlmsvcrtexistsstatst_size write_textopenflockLOCK_EXseeklockingfilenoLK_LOCKLOCK_UNOSErrorIOErrorLK_UNLCKclose) lock_pathfds r_usage_file_lockrHYs )),77I 4$777 }  4y''))4Y^^-=-=-E-J-JS7333 i1TG D D DB  ; KEM * * * * GGAJJJ N299;; : : :     B ....W%        ryy{{FOQ????W%          B ....W%        ryy{{FOQ????W%      s{?A2G-9EE-,E-8AGGG-J)6HJ)H*'J))H** J)5AI=<J)=JJ)JJ)c$tdz S)Nz.archiver&r#r r _archive_dirrJ}s ==: %%r cbtjtjSN)rnowrutc isoformatr#r r_now_isorPs < % % / / 1 11r valuerOptional[datetime]c|sdS tjt|}n#ttf$rYdSwxYw|j |tj}|S)zwxYw|S)zFReturn the total observed activity count across use/view/patch events.r) use_count view_count patch_count)rirbrVrW)r[totalres ractivity_countrosh E9  SC-A.. .EE:&    H  Ls'0AActdz }|stSt} |dD]^}|}|s|ddd}|r||_n2#t$r%}t d|Yd}~nd}~wwxYw|S) zReturn the set of skill names that were seeded from the bundled repo. Reads ~/.hermes/skills/.bundled_manifest (format: "name:hash" per line). Returns empty set if the file is missing or unreadable. z.bundled_manifestr-r.:r0rz#Failed to read bundled manifest: %sN) r$r6set read_text splitlinesstripsplitaddrBloggerdebug)manifestnameslinenamees r_read_bundled_manifest_namesrs  }}22H ??  uu eeE ?&&&88CCEE  D::<>>>>>>>? LsBC C:C55C:ctdz dz }|stS tj|d}t |tr|dpi}t |trZd| D}t}| D]}t |ts|d}t |tr| sXt|}|s||z } |}||n#t"t$f$rYwxYw|dz } | r)|t)| |j |Sn>#t"tjf$r%} t.d | Yd } ~ nd } ~ wwxYwtS) zReturn the set of skill names installed via the Skills Hub. Reads ~/.hermes/skills/.hub/lock.json (see tools/skills_hub.py :: HubLockFile). z.hubz lock.jsonr-r. installedc,h|]}t|Sr#)r).0ks r z,_read_hub_installed_names..s:::AQ:::r install_pathSKILL.mdfallbackz Failed to read hub lock file: %sN)r$r6rrjsonloadsrs isinstancedictrbkeysvaluesrrur is_absoluteresolve relative_torBrWrw_read_skill_namer}JSONDecodeErrorrxry) rFdatarr{ skills_direntryr skill_dirresolvedskill_mdr~s r_read_hub_installed_namesrsG  &4I     uu <z)--w-??@@ dD ! ! --3I)T** ::)9)9:::(]] &--//VVE%eT22! #(99^#<#$;F G> F41G>3F44AG>>H9H44H9cV ddlm}|}t|tr|dnd}t|tr#t |ddSn2#t $r%}td|Yd}~nd}~wwxYwdS)uWhether bundled built-in skills are eligible for curator pruning. Reads ``curator.prune_builtins`` from config (default True). Lazy import keeps this module importable without the CLI config layer (e.g. in the update/sync context); on any failure we fall back to the default. The real safety against a mass-prune is the curator's seed-on-first-sight, not this flag — built-ins only archive after a fresh inactivity window. r) load_configcuratorNprune_builtinsTz)Failed to read curator.prune_builtins: %s) hermes_cli.configrrrrbr Exceptionrxry)rcfgcurr~s r_prune_builtins_enabledrsE111111kmm$.sD$9$9Ccggi   t c4  9 0$7788 8 9 EEE @!DDDDDDDDE 4sA3A77 B&B!!B&c$tdz S)Nz.curator_suppressedr&r#r r_suppressed_filers ==0 00r ct}|stSt} |dD]B}|}|r*|ds||Cn2#t$r%}t d|Yd}~nd}~wwxYw|S)uBuilt-in skills the curator pruned — the re-seeder must leave archived. One skill name per line in ``~/.hermes/skills/.curator_suppressed``. This is what makes pruning a built-in durable: without it, ``hermes update`` would re-copy the bundled skill on the next sync. r-r.#z+Failed to read curator suppression list: %sN) rr6rrrsrtru startswithrwrBrxry)pathr{r|r~s rread_suppressed_namesr s   D ;;==uu eeEGNNGN44??AA  D::<E99E>c~|sdSt}||vr&||t|dSdS)zBRecord that a built-in skill was pruned, so sync won't restore it.N)rrwrrr{s radd_suppressed_namer6sS  ! # #E *&&&&&r c~|sdSt}||vr&||t|dSdS)z7Clear a built-in's suppression entry (e.g. on restore).N)rdiscardrrs rremove_suppressed_namer@sS  ! # #EU j!!!&&&&&r List[str]ct}|sgSt}t}t }t }g}|dD]}t|rt|r" | |n#t$rYEwxYwt||j j }||vrit|ry||vr|s||t!||s||t%t'|S)u Enumerate skills the curator may manage. Always includes agent-authored skills (those marked in ``.usage.json`` via ``skill_manage(action="create")``). When ``curator.prune_builtins`` is enabled, bundled built-in skills are ALSO included even though they have no agent-created usage record — their inactivity clock is anchored on first sight (see ``apply_automatic_transitions``). Hub-installed skills are never included; manually authored skills are not inferred from filesystem location. rr)r$r6rrr load_usagerglobrrrrWrr2r}rappend_is_curator_managed_recordrbrrr)basehubbundledrusager{rr}s rlist_agent_created_skill_namesrJsy ==D ;;== # % %C*,,G,..N LLEEJJz** !( + +   "( + +      & & & &    H 8?3GHHH 3;;   % %   7??"  LL    )%))D//::   T #e**  sB-- B:9B:ct}|sgStd|DS)aEnumerate skills in ``~/.hermes/skills/.archive/``. Archive layout is flat (``.archive//``) as set by ``archive_skill``, so the directory name is the skill name. Used by ``hermes curator list-archived`` to help users pass a name to ``hermes curator restore``. cDh|]}||jSr#is_dirr})rps rrz,list_archived_skill_names..s'HHHaQXXZZH16HHHr )rJr6riterdir) archive_roots rlist_archived_skill_namesrsO >>L     HH<#7#7#9#9HHH I IIr rrc |dddd}n#t$r|cYSwxYwd}|dD]}|}|dkr|rnbd }#|r\|d rG|d d d d }|r|cS|S)z9Parse the `name:` field from a SKILL.md YAML frontmatter.r-rX)r/errorsNiFrz---Tzname:rqr0z"')rsrBrvrur)rrtextin_frontmatterr|strippedrQs rrrs!!79!EEeteL N 4   ::<< u   !N   h11':: NN3**1-3355;;EBBE  Os " 11cttz}||vrdSt|duot|du S)z:Whether *skill_name* is neither bundled nor hub-installed.FN)rr_find_skill_dir_find_external_skill_dir)r off_limitss ris_agent_createdrsX-//2K2M2MMJZu ##t+ = $Z 0 0 < r c"|tvS)z6Whether *skill_name* was installed via the Skills Hub.)rrs ris_hub_installedrs 244 44r c"|tvS)z=Whether *skill_name* was seeded from the bundled repo skills.)rrs r is_bundledrs 577 77r cd|dS)Nskill 'zM' lives in skills.external_dirs; external skills are read-only to the curatorr#rs r_external_read_only_messagers 7* 7 7 7r skill_pathOptional[Path]c|t|rdSt|rdSt|rdSt|rt St |}|t| St |dSdS)uWhether the curator may track/archive *skill_name*. Agent-created skills are always eligible. Bundled built-ins become eligible only when ``curator.prune_builtins`` is enabled. Hub-installed and external skill-dir skills are NEVER eligible — they have an external upstream owner. Protected built-ins (``PROTECTED_BUILTIN_SKILLS``) are NEVER eligible regardless of any flag — they back load-bearing UX and must never be archived or consolidated. NFT)rrrrrrr)rr local_dirs ris_curation_eligiblers"8"D"DuJ''u ##u*)&((( ++I))4444 ++7u 4r ct|tsdS|ddkp|dduS)zEReturn True when a usage record opts a skill into curator management.F created_byagent agent_createdT)rrrb)r[s rrrsG fd # #u ::l # #w . U&**_2M2MQU2UUr c @dddddddttddd S)NrF) rrkrlr_r`rmra created_atstatepinned archived_at)rP STATE_ACTIVEr#r r _empty_recordrs6jj   r Dict[str, Dict[str, Any]]ct}|siS tj|d}nA#t tjf$r(}td||icYd}~Sd}~wwxYwt|tsiSi}| D],\}}t|tr||t|<-|S)zGRead the entire .usage.json map. Returns empty dict on missing/corrupt.r-r.zFailed to read %s: %sN) r'r6rrrsrBrrxryrritemsr)rrr~cleanrvs rrrs ==D ;;== z$..'.::;; T) * ,dA666  dD ! ! ')E 1 a   E#a&&M Ls(AB %BB B rct} |jddtjt |jdd\}} t j|dd5}tj ||d dd | t j | d d d n #1swxYwYt j ||d S#t$r( t j|n#t $rYnwxYwwxYw#t"$r)}t$d ||dYd }~d Sd }~wwxYw)uNWrite the usage map atomically. Best-effort — errors are logged, not raised.Tr)z.usage_rrrr-r.F)indent sort_keys ensure_asciiNzFailed to write %s: %sr)r'r2r3rrrrrrdumprrr?rXrrrBrrxry)rrrGtmp_pathrr~s r save_usager s ==DG $666'DK  6   H 2sW555 % $!t%PPPP $$$ % % % % % % % % % % % % % % % Jx & & & & &     (####        GGG -tQ FFFFFFFFFGssAD'C20AC C2CC2CC22 D$=DD$ DD$DD$$D'' E1EEct}||}t|tst St }|D]\}}||||S)zDReturn the record for *skill_name*, creating a fresh one if missing.)rrbrrrr setdefault)rrrecrrrs r get_recordr sx <._applyis? 5 5 :;;a?L (  r Nrr\rrrrrs r bump_viewr!cs. ++++ Jr c.dd}t||dS)zBump use_count and last_used_at. Called when a skill is actively used (e.g. loaded into the prompt path or referenced from an assistant turn). Tracks every skill regardless of provenance. rr\rrc|t|dpddz|d<t|d<dS)Nrkrr0r_rrs rrzbump_use.._applyus>sww{338q99A=K&jjNr Nrrr s rbump_user$os. )))) Jr c.dd}t||dS)zBump patch_count and last_patched_at. Called from skill_manage (patch/edit). Tracks every skill regardless of provenance. rr\rrc|t|dpddz|d<t|d<dS)Nrmrr0rarrs rrzbump_patch.._applys? !7!7!<1==AM!) r Nrrr s r bump_patchr'{s. ,,,, Jr c2d d}t||ddS) zOpt a skill created by skill_manage into curator management. Viewing or invoking a manually authored skill may still create telemetry, but only this explicit marker makes it eligible for automatic curation. rr\rrcd|d<dS)Nrrr#rs rrz"mark_agent_created.._applys#Lr TrNrrr s rmark_agent_createdr*s1 $$$$ J$??????r rctvrtd|dSd fd }t||d dS) zSet lifecycle state. No-op if *state* is invalid or the skill isn't curator-manageable (hub skills, or built-ins with pruning disabled).z"set_state: invalid state %r for %sNrr\rrcr|d<tkrt|d<dStkrd|d<dSdS)Nrr)STATE_ARCHIVEDrPr)rrs rrzset_state.._applysNG N " "!)C    l " "!%C   # "r Trr) _VALID_STATESrxryr)rrrs ` r set_stater/sg M!! 95*MMM&&&&&&  J$??????r rc8dfd }t||ddS) Nrr\rrc,t|d<dS)Nr)r)rrs rrzset_pinned.._applysV H r Trrr)rrrs ` r set_pinnedr2s<%%%%%% J$??????r c|sdS t5t}||vr||=t|ddddS#1swxYwYdS#t$r)}td||dYd}~dSd}~wwxYw)zFDrop a skill's usage entry entirely. Called when the skill is deleted.Nz!skill_usage.forget(%s) failed: %sTr)rHrr rrxryrs rforgetr4s X    ! !<||j d tj tjd z } ||np#t$rc}d dl} |t)|t)|n##t*$r}dd|fcYd}~cYd}~Sd}~wwxYwYd}~nd}~wwxYwt-|rt/|t1|t2dd|fS)asMove a curator-eligible skill directory to ~/.hermes/skills/.archive/. Returns (ok, message). Never archives hub-installed skills. Bundled built-ins are only archivable when ``curator.prune_builtins`` is enabled; when one is archived, its name is added to the suppression list so the update-time re-seeder leaves it archived instead of restoring it. NFrzY' is a protected built-in; it backs load-bearing UX and is never archived or consolidatedz!' is hub-installed; never archivezJ' is a bundled built-in; enable curator.prune_builtins to allow pruning itz ' not foundTr)zfailed to create archive dir: -z %Y%m%d%H%M%Srzfailed to archive: z archived to )rrrrrrrrJr3rBr}r6rrMrrNstrftimerenameshutilmoverrrrr/r-)rlocal_skill_dirrrr~destr:e2s r archive_skillr?s&j11O#;J#G#G#S1*====  O < <   + + H*HHH  J ' ' RQJQQQQ Q 9j 9 9 9   I7 77777i((>1*====>>L;4$7777 ;;;:q:::::::::; ). (D {{}}hgg(,x|2L2L2U2UVd2e2eggg5 555  5 KKID 2 2 2 2 5 5 54444 4 4 4 4 4 4 4 4 4 4 4 5 3 2 2 2 2 5*(J''' j.))) &&& &&sl3C C&C!C&!C&E G &G+0FG F<&F7,F<-G1G 7F<<GG cBtrdddfStrtsdddfSt}|sdSfd|dD}|s5dt fd |dDd }|sddd fS|d }tz }|rdd|fS ||nf#t$rYd dl } | t|t|n #t$r}dd|fcYd}~cYSd}~wwxYwYnwxYwttt d d|fS)u<Move an archived skill back to ~/.hermes/skills/. Restores to the flat top-level layout; original category nesting is NOT reconstructed. Refuses to restore under a name that now collides with a hub-installed skill — that would shadow the upstream version. Also refuses to restore over a bundled built-in UNLESS ``curator.prune_builtins`` is enabled (in which case built-ins are curator-managed and restoring is the documented way to lift a prune). Restoring clears any suppression entry so future updates may re-seed the built-in again. FrzA' is now hub-installed; restore would shadow the upstream versionz;' is now bundled; restore would shadow the upstream version)Fzno archive directorycRg|]#}||jk!|$Sr#r)rrrs r z!restore_skill..s3\\\ \qvQ[G[G[!G[G[G[r *r7cg|]}|rr|jrXt|jtz dkX|jtd|S)N)rr}rlenisdigit)rrrs rrBz!restore_skill..s   88:: F%%f-- KK#f++-33F3v;;<<(00224433r T)reversez' not found in archiverzdestination already exists: Nzfailed to restore: z restored to )rrrrJr6rrr$r9rBr:r;rrrr/r)rr candidatessrcr=r:r~rs` @r restore_skillrKsw ##  8j 8 8 8  * &=&?&?  8j 8 8 8   >>L    -,, ]\\\\//44\\\J  !!!    '--c22        CB BBBBB Q-C ==: %D {{}}<;T;;;;4 4 444  4 KKC#d)) , , , , 4 4 43333 3 3 3 3 3 3 3 3 4 - ,4:&&& j,''' &&& &&sB:DE30EE3 E-E( E-!E3(E--E32E3ct}|sdS|dD]J}t|rt |r"t ||jj|kr |jcSKdS)zLocate the directory for a skill by its frontmatter `name:` field. Handles both flat (~/.hermes/skills//SKILL.md) and category-nested (~/.hermes/skills///SKILL.md) layouts. Nrr)r$r6rrrrr2r})rrrs rrr@s ==D ;;==tJJz**## !( + +   !( + +   Hx/C D D D R R? " " " S 4r c ddlm}|ddD]i}|s|dD]<}t |rt ||jj|kr |jccS=jdS)zBLocate a skill under configured external dirs by frontmatter name.r)get_all_skills_dirsr0Nrr)agent.skill_utilsrNr6rrrr2r})rrNrrs rrrSs555555##%%abb)''{{}}   :.. ' 'H%h// 8?3GHHHJVV&&&&&W ' 4r List[Dict[str, Any]]ct}g}tD]}||}t|t}t|tr|n t }t }|D]\}}|||d|i|d|i} t| | d<t| | d<| | |S)aReturn a list of {name, state, pinned, last_activity_at, ...} records for every curator-managed skill. Missing usage records are backfilled with defaults so callers can always index fields. Each row carries ``_persisted``: True when a real record exists in ``.usage.json``, False when the row is a fresh backfill (e.g. a built-in seen for the first time). The curator uses this to seed the inactivity clock instead of treating an unrecorded skill as ancient. r} _persistedlast_activity_atro) rrrbrrrrrrhror) rrowsr}rf persistedrrrrrows ragent_created_reportrWfs <zusage_report..s air )re)r$r6rrrrrrr2r}rwrbrrrrrrYrhrorr) rrrTseenrr}rfrUrbase_recrrrVs r usage_reportr`s ==D ;;== <rms0#"""""  %%%%%%''''''''8888888888888888,,,,,,LLLLLLLL  8 $ $  LLLL   E          {N;  & 2222(((())))   F&&&&2222    (.####L*1111*WWWW,''''''''4444n J J J J*5555 8888 4VVVV     (GGGG0    hhhh,LQYYYYYY@              @@@@ @ @ @ @@@@@ X X X X$:':':':'zH'H'H'H'V&    &4    &1&1&1&1&1&1s6A$$A?,A10A?1A96A?8A99A?>A?