`gjUdZddlmZddlZddlZddlZddlZddlmZddl m Z m Z ddl m Z ddl mZmZmZmZmZmZddlmZdd lmZmZej2eZdZ ddlZd Zd Z d Z!ee e!hZ"d hZ#de$d<d@dZ%dAdZ&dAdZ'edZ(dAdZ)dBdZ*dCdZ+dDdZ,dEdZ-dFdZ.dFdZ/dGdZ0dAdZ1dFdZ2dHdZ3dIdZ4dId Z5dJd!Z6dJd"Z7dKd#Z8d@d$Z9d@d%Z:d@d&Z;dLd'ZdPd*Z?dQd+Z@dRd,ZAdSd-ZBdId.ZCd/d0dTd1ZDdId2ZEdId3ZFdId4ZGdId5ZHdUd6ZIdVd7ZJdId8ZKdWd9ZLdWd:ZMdXd;ZNdXd<ZOdYd=ZPdLd>ZQdYd?ZRy#e$rdZ ddlZn #e$rYnwxYwYwxYw)ZaSkill 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_SKILLSc|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. )r skill_names D/root/.hermes/venv/lib/python3.12/site-packages/tools/skill_usage.pyis_protected_builtinrGs 1 11ctdz S)Nskillsrrr _skills_dirr!Qs  x ''rctdz S)Nz .usage.jsonr!r rr _usage_filer$Us == ((rc# Ktjd}|jjddt t dyt r@|j r|jjdk(r|jddt|t rd nd d} tr%t j|tjnD|jdt j|jt j d dtr& t j|tj"nKt rE |jdt j|jt j(d |j+y#t$t&f$rY"wxYw#t$t&f$rY7wxYw#tr; t j|tj"nv#t$t&f$rYnewxYwt r[ |jdt j|jt j(d n#t$t&f$rYnwxYw|j+wxYww) 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_lockrEYs )),7I 4$7 }  y'')Y^^-=-E-E-JS73 iTG DB  KKEMM * GGAJ NN299; :   B .  ryy{FOOQ?  W%   W%     B .W%     ryy{FOOQ?W%    sB$J'A3G J!$F"J AF7J"F41J3F44J7G JG  J J$G98J9H J H  JAIJI,)J+I,,JJctdz S)Nz.archiver#r rr _archive_dirrG}s =: %%rcdtjtjj SN)rnowrutc isoformatr rr_now_isorMs << % / / 11rc|sy tjt|}|j |j tj}|S#ttf$rYywxYw)z> L?sAB%B%% C.C  Cctdz dz }|js tS tj|j d}t |tr<|jdxsi}t |tr|jDchc] }t|}}t}|jD]}t |ts|jd}t |tr|jsFt|}|js||z } |j} | j!|j| dz } | js|j't)| | j*|StScc}w#t"t$f$rYwxYw#t"tj,f$r)} t.j1d | Yd } ~ tSd } ~ wwxYw) 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+ installed install_pathSKILL.mdfallbackz Failed to read hub lock file: %sN)r!r3rmjsonloadsrn isinstancedictr\keysrQvaluesrpr is_absoluteresolve relative_tor?rSrr_read_skill_namerxJSONDecodeErrorrsrt) rCdatar|krv skills_direntryr} skill_dirresolvedskill_mdrys r_read_hub_installed_namesrs  &4I    u <zz)--w-?@ dD !-3I)T*)2)9:AQ::(] &--/VE%eT2 #(99^#F??GHG??Hc ddlm}|}t|tr|j dnd}t|trt |j ddS y#t $r }tjd|Yd}~yd}~wwxYw)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\bool Exceptionrsrt)rcfgcurrys r_prune_builtins_enabledrsE1m$.sD$9cggi t c4  0$78 8 !  E @!DD EsAA B(BBctdz S)Nz.curator_suppressedr#r rr_suppressed_filers =0 00rcvt}|js tSt} |jdj D]8}|j }|s|j dr(|j|: |S#t$r!}tjd|Yd}~|Sd}~wwxYw)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) rr3rmrnrorp startswithrrr?rsrt)pathrvrwrys rread_suppressed_namesr s  D ;;=u eEGNNGN4??A D:::D D1 D! D1! D-*D1,D--D11D44 E=EEc`|syt}||vr|j|t|yy)zBRecord that a built-in skill was pruned, so sync won't restore it.N)rrrrrrvs radd_suppressed_namer6s1  ! #E *&rc`|syt}||vr|j|t|yy)z7Clear a built-in's suppression entry (e.g. on restore).N)rdiscardrrs rremove_suppressed_namer@s1  ! #EU j!&rcBt}|jsgSt}t}t }t }g}|j dD]}t|rt|r |j|t||jj}||vrSt|r_||vr|sf|j|xt!|j#|s|j|t%t'|S#t$rYwxYw)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)r!r3rrzr load_usagerglobrrrrSrr/rxrappend_is_curator_managed_recordr\rrm)basehubbundledrusagervrrxs rlist_agent_created_skill_namesrJs =D ;;= # %C*,G,.N LEEJJz* !( +  "( +     & 8??3G3GH 3;   %  7?" LL  )%))D/:  T=> #e* +   s4D DDct}|jsgSt|jDchc]}|j s|j !c}Scc}w)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``. )rGr3riterdiris_dirrx) archive_rootps rlist_archived_skill_namesrsJ >L     <#7#7#9HaQXXZ166H IIHs A AcZ |jdddd}d}|jdD]l}|j}|dk(r|r|Sd } |s#|j d s5|jd d d jjd }|sj|cS|S#t$r|cYSwxYw)z9Parse the `name:` field from a SKILL.md YAML frontmatter.r*rT)r,errorsNiFrz---Tzname:rlr-z"')rnr?rqrpr)rrtextin_frontmatterrwstrippedrUs rrrs!!79!EetLN 4 ::< u  O "N  h11':NN3*1-335;;EBE   O sB B*)B*cpttz}||vryt|duxr t|du S)z:Whether *skill_name* is neither bundled nor hub-installed.FN)rzr_find_skill_dir_find_external_skill_dir)r off_limitss ris_agent_createdrsG-/2K2MMJZ #t+ = $Z 0 < rc|tvS)z6Whether *skill_name* was installed via the Skills Hub.)rrs ris_hub_installedrs 24 44rc|tvS)z=Whether *skill_name* was seeded from the bundled repo skills.)rzrs r is_bundledrs 57 77rcd|dS)Nskill 'zM' lives in skills.external_dirs; external skills are read-only to the curatorr rs r_external_read_only_messagers *7 7rc| t|ryt|ryt|ryt|r t St |}| t| St |yy)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. FT)rrrrrrr)r skill_path local_dirs ris_curation_eligiblersk"8"DJ' #*&(( +I))444 +7 rcvt|tsy|jddk(xs|jdduS)zEReturn True when a usage record opts a skill into curator management.F created_byagent agent_createdT)rrr\)r]s rrrs7 fd # ::l #w . U&**_2MQU2UUrc 6dddddddttddd S)NrF) rrerfrYrZrgr[ created_atstatepinned archived_at)rM STATE_ACTIVEr rr _empty_recordrs/j  rct}|jsiS tj|j d}t|tsiSi}|jD]$\}}t|ts||t|<&|S#t tj f$r#}tjd||icYd}~Sd}~wwxYw)zGRead the entire .usage.json map. Returns empty dict on missing/corrupt.r*r+zFailed to read %s: %sN) r$r3rrrnr?rrsrtrritemsrQ)rrrycleanrvs rrrs =D ;;= zz$..'.:; dD ! ')E 1 a E#a&M L T)) * ,dA6 s%BC )CC C ct} |jjddtjt |jdd\}} t j|dd5}tj||d dd |jt j|jd d d t j||y #1swY xYw#t$r' t j|#t $rYwxYwwxYw#t"$r#}t$j'd ||dYd }~y d }~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$r/r0rrrQrrrdumprrr<rTrrr?rrsrt)rrrDtmp_pathrrys r save_usagers =DG $6''DKK 6 H 2sW5 % $!t%P $ % JJx &  % %    (#      G -tQ FFGsgA DC)0AC>C)C&"C)) D3D D DDDDD E%EEct}|j|}t|ts t St }|j D]\}}|j |||S)zDReturn the record for *skill_name*, creating a fresh one if missing.)rr\rrrr setdefault)rrrecrrrs r get_recordr s\ ._applyis1 5 :;a?L (  rNrDict[str, Any]returnNoner rrs r bump_viewrcs + Jrc$dd}t||y)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. cft|jdxsddz|d<t|d<y)Nrerr-rYrrs rrzbump_use.._applyus0sww{38q9A=K&jNrNrrrs rbump_useros ) Jrc$dd}t||y)zBump patch_count and last_patched_at. Called from skill_manage (patch/edit). Tracks every skill regardless of provenance. cft|jdxsddz|d<t|d<y)Nrgrr-r[rrs rrzbump_patch.._applys1 !7!<1=AM!) rNrrrs r bump_patchr{s , Jrc(dd}t||dy)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. cd|d<y)Nrrr rs rrz"mark_agent_created.._applys #LrTrNrrrs rmark_agent_createdr s $ J$?rcntvrtjd|ydfd }t||dy)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 %sNc\|d<tk(rt|d<ytk(rd|d<yy)Nrr)STATE_ARCHIVEDrMr)rrs rrzset_state.._applys7G N "!)C  l "!%C #rTrr) _VALID_STATESrsrtr )rrrs ` r set_stater%s4 M! 95*M&  J$?rc.dfd }t||dy)Nc"t|d<y)Nr)r)rrs rrzset_pinned.._applysV H rTrrr)rrrs ` r set_pinnedr(s% J$?rc|sy t5t}||vr||=t|dddy#1swYyxYw#t$r#}tj d||dYd}~yd}~wwxYw)zFDrop a skill's usage entry entirely. Called when the skill is deleted.Nz!skill_usage.forget(%s) failed: %sTr)rErrrrsrtrs rforgetr*st X   !AA A- A((A-ct|}|t| dt|fSt||s.t |rdd|dfSt |rdd|dfSdd|dfS|}|dd|dfSt |r dt|fSt} |jdd ||jz }|jrD||jd tjtjj!d z } |j#|t-|r t/|t1|t2dd|fS#t$r}dd |fcYd}~Sd}~wwxYw#t$rV}d dl} |j't)|t)|n"#t*$r}dd|fcYd}~cYd}~Sd}~wwxYwYd}~d}~wwxYw)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 )rrrrrrrrGr0r?rxr3rrJrrKstrftimerenameshutilmoverQrrrr%r#)rlocal_skill_dirrrrydestr/e2s r archive_skillr4s&j1O#;J#G#S1*===  O <  +*&HH  J 'GJL;4$7 ).. (D {{} 0(,,x||2L2U2UVd2e1fgg5*J' j.) <v& &&1 ;6qc:::; 5 5 KKID 2 5/t44 4 4 5 3 5slEE! E EEE! G*F;/$FF; F3F.#F3$F;(G.F33F;;Gc t|rdd|dfSt|rtsdd|dfSt}|j sy|j dDcgc]%}|j s|j|k(s$|'}}|s|d}t|j dDcgc]y}|j rg|jj|rLt|jt|z dk(r(|jt|d jr|{c}d }|sdd|d fS|d }t|z }|j rdd|fS |j|t'|t)|t*d d|fScc}wcc}w#t$rLd d l} |j!t#|t#|n#t$$r}dd|fcYd }~cYSd }~wwxYwYwxYw)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 directory*r,NT)reversez' not found in archiverzdestination already exists: zfailed to restore: z restored to )rrrrGr3rrrxrrlenisdigitr!r.r?r/r0rQrrr%r) rrr candidatesrsrcr2r/rys r restore_skillr=s #j\"8 8  *&=&?j\"8 8   >L    , *//4\ qvvQ[G[!\J\ F%F"" G70$GG7 G1G,$G1%G7,G11G76G7ct}|jsy|jdD]L}t|rt |rt ||j j|k(s@|j cSy)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)r!r3rrrrr/rx)rrrs rrr@sm =D ;;=JJz*# !( +  !( +  Hx/C/C D R?? " # rcddlm}|ddD]i}|js|jdD]B}t |rt ||j j|k(s4|j ccSky)zBLocate a skill under configured external dirs by frontmatter name.r)get_all_skills_dirsr-Nr~r)agent.skill_utilsr@r3rrrr/rx)rr@rrs rrrSsu5#%ab)'{{}  :. 'H%h/8??3G3GHJV&  '' rct}g}tD]}|j|}t|t}t|tr|n t }t }|j D]\}}|j||d|i|d|i} t| | d<t| | d<|j| |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. rx _persistedlast_activity_atrj) rrr\rrrrrrcrjr) rrowsrxra persistedrrrrrows ragent_created_reportrHfs zusage_report..s air)r`)r!r3rrmrrrr/rxrrr\rrrrrrJrcrjrr) rrrEseenrrxrarFrbase_recrrrGs r usage_reportrQs: =D ;;= r`s0#  %'88,L   8 $    {N;  &( 2()  F&2 (.#L*1*W,''4n J*5 8 4V  (G0 h,LQY@     @ @@ X$:'zH'V& &4 &1A E      s6!D99EEEE E EEE