p#jzdZddlmZddlZddlZddlZddlZddlmZddl m Z m Z ddl m Z ddl mZmZmZmZmZmZddlmZdd lmZejeZdZ ddlZn#e$rdZ ddlZn #e$rYnwxYwYnwxYwd Zd Zd Z eee hZ!dTdZ"dTdZ#edZ$dTdZ%dUdZ&dVdZ'dWdZ(dXdZ)dYd Z*dYd!Z+dZd#Z,dTd$Z-dYd%Z.d[d(Z/d\d*Z0d\d+Z1d]d-Z2d]d.Z3d^d1Z4d_d2Z5d_d3Z6d_d4Z7d_d5Z8d`d6Z9dad7Z:dbd9Z;dcd;Zd>d?dedAZ?d\dBZ@d\dCZAd\dDZBd\dEZCdfdGZDdgdIZEd\dJZFdhdLZGdhdMZHdidOZIdjdQZJdkdRZKdjdSZLdS)laSkill 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_pathactivestalearchivedreturnrc$tdz S)Nskillsr6/home/ubuntu/.hermes/hermes-agent/tools/skill_usage.py _skills_dirr;s   x ''rc$tdz S)Nz .usage.jsonrrrr _usage_filer?s === ((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_lockr>Cs )),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.archiverrrr _archive_dirr@gs ==: %%rstrcbtjtjS)N)rnowrutc isoformatrrr_now_isorFks < % % / / 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)r_rXrLrM)rQtotalr[s ractivity_countresh E9  SC-A.. .EE:&    H  Ls'0AASet[str]ctdz }|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) rr,set read_text splitlinesstripsplitaddr8loggerdebug)manifestnameslinenamees r_read_bundled_manifest_namesrvs  }}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)rA).0ks r z,_read_hub_installed_names..s:::AQ:::r install_pathSKILL.mdfallbackz Failed to read hub lock file: %sN)rr,rijsonloadsrj isinstancedictrXkeysvaluesrArlr is_absoluteresolve relative_tor8rMrn_read_skill_namertJSONDecodeErrorrorp) r<datarxrr skills_direntryr} skill_dirresolvedskill_mdrus r_read_hub_installed_namesrsG  &4I     uu <z)--w-??@@ dD ! ! --3I)T** ::)9)9:::(]] &--//VVE%eT22! #(99^#<#$;F G> F41G>3F44AG>>H9H44H9boolcV 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.configrrrrXr Exceptionrorp)rcfgcurrus 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_suppressedrrrr_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) rr,rirjrkrl startswithrnr8rorp)pathrrrsrus rread_suppressed_namesrs   D ;;==uu eeEGNNGN44??AA  D::<E99E> skill_namec~|sdSt}||vr&||t|dSdS)zBRecord that a built-in skill was pruned, so sync won't restore it.N)rrnrrrrs radd_suppressed_namer sS  ! # #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]c~t}|sgSt}t}t }t }g}|dD]}t|r ||n#t$rY5wxYwt||j j }||vrY||vr|s`| |vt||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. r~r)rr,rrvr load_usagerglobrrrMrr(rtappend_is_curator_managed_recordrXrri)basehubbundledrusagerrrrts rlist_agent_created_skill_namesr4sO ==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|]}||jSris_dirrt)rzps rr|z,list_archived_skill_names..ms'HHHaQXXZZH16HHHr)r@r,riterdir) archive_roots rlist_archived_skill_namesrcsO >>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#rN)r%errorsNiFrz---Tzname:rhr&z"')rjr8rmrlr)rrtextin_frontmatterrsstrippedrGs rrrps!!79!EEeteL N 4   ::<< u   !N   h11':: NN3**1-3355;;EBBE  Os " 11cDttz}||vS)z:Whether *skill_name* is neither bundled nor hub-installed.)rvr)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.)rvrs r is_bundledrs 577 77rcbt|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. FT)rrrrs ris_curation_eligiblers: ##u*)&((( 4rct|tsdS|ddkp|dduS)zEReturn True when a usage record opts a skill into curator management.F created_byagent agent_createdT)rrrX)rQs rrrsG fd # #u ::l # #w . U&**_2M2MQU2UUrc @dddddddttddd S)NrF) rrarbrUrVrcrW created_atstatepinned archived_at)rF STATE_ACTIVErrr _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) rr,rrrjr8rrorprritemsrA)rrrucleanr{vs 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.Trz.usage_rrrr#r$F)indent sort_keys ensure_asciiNzFailed to write %s: %sr)rr(r)rrrArrrdumprrr5rNrrr8rrorp)rrr=tmp_pathrrus 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.)rrXrrrr setdefault)rrrecrr{rs r get_recordrsx <rrrXrrrrrorprrrus rseed_record_if_missingrs[ 1*==h     <rrXrrrrrrorp)rmutatorrrrrus r_mutater  sQ  Y $ -A*-M-M  F     <._apply3s? 5 5 :;;a?L (  rNrrRrrr rrs r bump_viewr-s. ++++ 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. rrRrrc|t|dpddz|d<t|d<dS)Nrarr&rUr rs rrzbump_use.._apply?s>sww{338q99A=K&jjNrNrrrs rbump_user9s. )))) Jrc.dd}t||dS)zBump patch_count and last_patched_at. Called from skill_manage (patch/edit). Tracks every skill regardless of provenance. rrRrrc|t|dpddz|d<t|d<dS)Nrcrr&rWr rs rrzbump_patch.._applyJs? !7!7!<1==AM!) rNrrrs r bump_patchrEs. ,,,, 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. rrRrrcd|d<dS)Nrrrrs rrz"mark_agent_created.._applyVs#LrTrNrrrs rmark_agent_createdrPs1 $$$$ 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 %sNrrRrrcr|d<tkrt|d<dStkrd|d<dSdS)Nrr)STATE_ARCHIVEDrFr)rrs rrzset_state.._applyasNG N " "!)C    l " "!%C   # "rTrr) _VALID_STATESrorpr )rrrs ` r set_stater![sg M!! 95*MMM&&&&&&  J$??????rrc8dfd }t||ddS) NrrRrrc,t|d<dS)Nr)r)rrs rrzset_pinned.._applyksV H rTrrr)rrrs ` r set_pinnedr$js<%%%%%% 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)r>rrrrorprs rforgetr&ps 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 'z!' is hub-installed; never archivezJ' is a bundled built-in; enable curator.prune_builtins to allow pruning itNz ' not foundTrzfailed to create archive dir: -z %Y%m%d%H%M%Srzfailed to archive: z archived to )rr_find_skill_dirr@r)r8rtr,rrCrrDstrftimerenameshutilmoverArrrr!r)rrrrudestr.e2s r archive_skillr2s] + + 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.))) &&& &&slA// B 9B?B B *D E- E(0E?E( E  EE E(E-E  E((E-c6trdddfStrtsdddfSt}|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!|$Srrrzrrs r z!restore_skill..s3\\\ \qvQ[G[G[!G[G[G[r*cvg|]5}||jd3|6S)r*)rrtrr5s rr6z!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 )rrrr@r,rrrr-r8r.r/rArrr!r)rr candidatessrcr0r.rus` 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. Nr~r)rr,rrrr(rt)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. rt _persistedlast_activity_atre) rrrXrrrrrr^rer) rrowsrtr\ persistedrrr{rrows ragent_created_reportrFs <zusage_report..Ts air)r[)rr,rrirrrr(rtrnrXrrrrrrHr^rerr) rrrCseenrrtr\rDrbase_recr{rrEs r usage_reportrO.s ==D ;;== <r@rFrPr^rervrrrrrrrrrrrrrrrrrrrrr rrrrr!r$r&r2r<r+rFrHrOrrrr\s0#"""""  %%%%%%''''''''8888888888888888,,,,,,444444  8 $ $  LLLL   E          {N; (((())))   F&&&&2222    (.####L*1111*WWWW,'''''''',,,,^ J J J J*(((( 5555 8888    VVVV     (GGGG0    hhhh,LQYYYYYY@              @@@@ @ @ @ @@@@@ X X X X$/'/'/'/'d;';';';'|*4    &1&1&1&1&1&1s6A!!A<)A.-A<.A63A<5A66A<;A<