oq'jUdZddlmZddlZddlZddlZddlZddlmZddl m Z m Z ddl m Z ddl mZmZmZmZmZmZddlmZdd lmZejeZdZ ddlZn#e$rdZ ddlZn #e$rYnwxYwYnwxYwd Zd Zd Z eee hZ!d hZ"de#d<dWdZ$dXdZ%dXdZ&edZ'dXdZ(dYdZ)dZdZ*d[d"Z+d\d$Z,d]d%Z-d]d&Z.d^d'Z/dXd(Z0d]d)Z1d_d,Z2d`d-Z3d`d.Z4dad0Z5dad1Z6dbd4Z7dWd5Z8dWd6Z9dWd7Z:dWd8Z;dcd9Zdfd>Z?dgd?Z@d`d@ZAdAdBdhdDZBd`dEZCd`dFZDd`dGZEd`dHZFdidJZGdjdLZHd`dMZIdkdOZJdkdPZKdldRZLdmdTZMdndUZNdmdVZOdS)oaSkill 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_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 6/home/ubuntu/.hermes/hermes-agent/tools/skill_usage.pyis_protected_builtinrGs 1 11rc$tdz S)Nskillsrrr _skills_dirr#Qs   x ''rc$tdz S)Nz .usage.jsonr#r"rr _usage_filer&Us === ((rc#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_lockrGYs )),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"rr _archive_dirrI}s ==: %%rcbtjtjS)N)rnowrutc isoformatr"rr_now_isorNs < % % / / 1 11rvaluerOptional[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)rgr`rTrU)rYtotalrcs ractivity_countrmsh 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-:r/rz#Failed to read bundled manifest: %sN) r#r5set read_text splitlinesstripsplitaddrAloggerdebug)manifestnameslinenamees r_read_bundled_manifest_namesr}s  }}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#r5rpjsonloadsrq isinstancedictr`keysvaluesrrsr is_absoluteresolve relative_torArUru_read_skill_namer{JSONDecodeErrorrvrw) rEdatarry 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.configrrrr`r Exceptionrvrw)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"rr_suppressed_filers ==0 00rct}|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) rr5rprqrrrs startswithrurArvrw)pathryrzr|s rread_suppressed_namesr s   D ;;==uu eeEGNNGN44??AA  D::<rV BaseExceptionunlinkrArrvrw)ryrrrFtmpfr|s r_write_suppressed_namesr s   DW $666yy''5+@44bA"s4;'7'7@V_efffC 2sW555 %  $$$ % % % % % % % % % % % % % % % JsD ! ! ! ! !     #        WWW CQQU VVVVVVVVVWssA1E DAC5) D5C99D<C9=D E "D76E 7 EE EE  E E>E99E>c~|sdSt}||vr&||t|dSdS)zBRecord that a built-in skill was pruned, so sync won't restore it.N)rrurrrys radd_suppressed_namer6sS  ! # #E *&&&&&rc~|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|r ||n#t$rY5wxYwt||j j }||vrYt|ri||vr|sp||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#r5rr}r load_usagerglobrrrUrr1r{rappend_is_curator_managed_recordr`rrp)basehubbundledrusageryrr{s rlist_agent_created_skill_namesrJsd ==D ;;== # % %C*,,G,..N LLEEJJz** !( + +      & & & &    H 8?3GHHH 3;;   % %   7??"  LL    )%))D//::   T #e**  sB B*)B*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)rIr5riterdir) archive_roots rlist_archived_skill_namesr}sO >>L     HH<#7#7#9#9HHH I IIrrrc |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,rV)r.errorsNiFrz---Tzname:ror/z"')rqrArtrsr)rrtextin_frontmatterrzstrippedrOs rrrs!!79!EEeteL N 4   ::<< u   !N   h11':: NN3**1-3355;;EBBE  Os " 11cDttz}||vS)z:Whether *skill_name* is neither bundled nor hub-installed.)r}r)r off_limitss ris_agent_createdrs$-//2K2M2MMJ Z ''rc"|tvS)z6Whether *skill_name* was installed via the Skills Hub.)rrs ris_hub_installedrs 244 44rc"|tvS)z=Whether *skill_name* was seeded from the bundled repo skills.)r}rs r is_bundledrs 577 77rct|rdSt|rdSt|rtSdS)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 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. FT)rrrrrs ris_curation_eligiblersOJ''u ##u*)&((( 4rct|tsdS|ddkp|dduS)zEReturn True when a usage record opts a skill into curator management.F created_byagent agent_createdT)rrr`)rYs rrrsG fd # #u ::l # #w . U&**_2M2MQU2UUrc @dddddddttddd S)NrF) rrirjr]r^rkr_ created_atstatepinned archived_at)rN STATE_ACTIVEr"rr _empty_recordrs6jj   rDict[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&r5rrrqrArrvrwrritemsr)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&r1r2rrrrrrdumprrr>rVrrrArrvrw)rrrFtmp_pathrr|s r save_usagers ==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.)rr`rrrr setdefault)rrrecrrrs r get_recordrsx <._applyQs? 5 5 :;;a?L (  rNrrZrrrrrs r bump_viewrKs. ++++ Jrc.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. rrZrrc|t|dpddz|d<t|d<dS)Nrirr/r]rrs rrzbump_use.._apply]s>sww{338q99A=K&jjNrNrrrs rbump_userWs. )))) Jrc.dd}t||dS)zBump patch_count and last_patched_at. Called from skill_manage (patch/edit). Tracks every skill regardless of provenance. rrZrrc|t|dpddz|d<t|d<dS)Nrkrr/r_rrs rrzbump_patch.._applyhs? !7!7!<1==AM!) rNrrrs r bump_patchrcs. ,,,, Jrc2d 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. rrZrrcd|d<dS)Nrrr"rs rrz"mark_agent_created.._applyts#LrTr Nrrrs rmark_agent_createdr ns1 $$$$ J$??????rrctvrtd|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 %sNrrZrrcr|d<tkrt|d<dStkrd|d<dSdS)Nrr)STATE_ARCHIVEDrNr)rrs rrzset_state.._applysNG N " "!)C    l " "!%C   # "rTr r) _VALID_STATESrvrwr)rrrs ` r set_stater%ysg M!! 95*MMM&&&&&&  J$??????rrc8dfd }t||ddS) NrrZrrc,t|d<dS)Nr)r)rrs rrzset_pinned.._applysV H rTr rr)rrrs ` r set_pinnedr(s<%%%%%% J$??????rc|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)rGrrrrvrwrs rforgetr*s X    ! !<||jd tj tj  d z } ||np#t $rc}d dl} |t#|t#|n##t$$r}dd|fcYd}~cYd}~Sd}~wwxYwYd}~nd}~wwxYwt'|rt)|t+|t,dd|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. Fskill 'zY' 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 itNz ' not foundTr(zfailed to create archive dir: -z %Y%m%d%H%M%Srzfailed to archive: z archived to )rrr_find_skill_dirrIr2rAr{r5rrKrrLstrftimerenameshutilmoverrrrr%r#)rrrr|destr2e2s r archive_skillr6s + +   + + H*HHH  J ' ' RQJQQQQ Q 9j 9 9 9   ++I7 77777>>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.))) &&& &&sl.B B!BB!B!D F!E?&0EE? E7!E2'E7(E?,F2E77E??Fc6trdddfStrtsdddfSt}|sdSfd|dD}|s0t 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. Fr-zA' is now hub-installed; restore would shadow the upstream versionz;' is now bundled; restore would shadow the upstream version)Fzno archive directorycRg|]#}||jk!|$Sr"rrrrs r z!restore_skill..s3\\\ \qvQ[G[G[!G[G[G[r*cvg|]5}||jd3|6S)r.)rr{rr9s rr:z!restore_skill..s^ D D D1  D v00J1A1A1ABB DQ D D DrT)reversez' not found in archiverzdestination already exists: Nzfailed to restore: z restored to )rrrrIr5rrr#r1rAr2r3rrrr%r)rr candidatessrcr4r2r|s` r restore_skillr@sj ##  8j 8 8 8  * &=&?&?  8j 8 8 8   >>L    -,, ]\\\\//44\\\J   D D D D **3// D D D   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,''' &&& &&sB4D E-0E  E- E'E"E'E-"E''E-,E-Optional[Path]ct}|sdS|dD]:}t|rt ||jj|kr |jcS;dS)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#r5rrrr1r{)rrrs rr/r/s ==D ;;==tJJz**## !( + +   Hx/C D D D R R? " " " S 4rList[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_atrm) rrr`rrrrrrfrmr) rrowsr{rd persistedrrrrrows ragent_created_reportrJ*s <zusage_report..ws air)rc)r#r5rrprrrr1r{rur`rrrrrrLrfrmrr) rrrGseenrr{rdrHrbase_recrrrIs r usage_reportrSQs ==D ;;== <rasW0#"""""  %%%%%%''''''''8888888888888888,,,,,,444444  8 $ $  LLLL   E          {N;  & 2222(((())))   F&&&&2222    (.####L*1111*WWWW,''''''''0000f J J J J*(((( 5555 8888 $VVVV     (GGGG0    hhhh,LQYYYYYY@              @@@@ @ @ @ @@@@@ X X X X$4'4'4'4'n;';';';'|*4    &1&1&1&1&1&1s6A""A=*A/.A=/A74A=6A77A=<A=