iEdZddlmZddlZddlZddlZddlZddlmZmZddl m Z ddl m Z m Z mZmZmZmZmZddlmZejeZdZd Zd ZeeehZd>d Zd>dZd>dZd?dZd@dZ dAdZ!dBdZ"dCdZ#dCdZ$dDd Z%dEd#Z&dFd&Z'dGd'Z(dHd)Z)dId,Z*dJd-Z+dKd.Z,dKd/Z-dKd0Z.dKd1Z/dLd3Z0dMd5Z1dKd6Z2dNd8Z3dNd9Z4dOd;Z5dPd=Z6dS)QavSkill 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: "agent-created" == not in .bundled_manifest AND not in .hub/lock.json. The curator only ever mutates agent-created skills. 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)datetimetimezone)Path)AnyDictIterableListOptionalSetTupleget_hermes_homeactivestalearchivedreturnrc$tdz S)Nskillsr6/home/ubuntu/.hermes/hermes-agent/tools/skill_usage.py _skills_dirr-s   x ''rc$tdz S)Nz .usage.jsonrrrr _usage_filer1s === ((rc$tdz S)Nz.archiverrrr _archive_dirr5s ==: %%rstrcbtjtjS)N)rnowrutc isoformatrrr_now_isor$9s < % % / / 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=r6r*r+)r/totalr9s ractivity_countrC^sh 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_manifestutf-8encoding:rz#Failed to read bundled manifest: %sN) rexistsset read_text splitlinesstripsplitaddOSErrorloggerdebug)manifestnameslinenamees r_read_bundled_manifest_namesrZms  }}22H ??  uu eeE ?&&&88CCEE  D::<>>>>>>>? LsBC C:C55C:ctdz dz }|stS tj|d}t |trJ|dpi}t |trd| DSn>#ttj f$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.jsonrFrG installedc,h|]}t|Sr)r).0ks r z,_read_hub_installed_names..s9991A999rz Failed to read hub lock file: %sN)rrKrLjsonloadsrM isinstancedictr6keysrRJSONDecodeErrorrSrT) lock_pathdatar\rYs r_read_hub_installed_namesris  &4I     uu <z)--w-??@@ dD ! ! :--3I)T** :99 (8(89999 T) *<<< 7;;;;;;;;< 55LsBCC;C66C; List[str]ct}|sgSt}t}||z}g}|dD]} ||}n#t $rY%wxYw|j}|r(|dds |ddkrZt||j j }||vrz| |tt|S)aEnumerate skills that were authored by the agent (or user), NOT by a bundled or hub-installed source. The curator operates exclusively on this set. Bundled / hub skills are maintained by their upstream sources and must never be pruned here. SKILL.mdr. node_modulesfallback)rrKrZrirglob relative_tor+parts startswith_read_skill_nameparentrXappendsortedrL) basebundledhub off_limitsrVskill_mdrelrsrXs rlist_agent_created_skill_namesrs" ==D ;;== *,,G # % %C3JEJJz**   &&t,,CC    H    eAh))#.. %(n2L2L 8?3GHHH :    T #e**  s A66 BBr}rpc |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.rFr,)rHerrorsNiF z---Tzname:rIrJz"')rMrRrPrOrt)r}rptextin_frontmatterrWstrippedr%s rrurus!!79!EEeteL N 4   ::<< u   !N   h11':: NN3**1-3355;;EBBE  Os " 11 skill_nameboolcDttz}||vS)z:Whether *skill_name* is neither bundled nor hub-installed.)rZri)rr|s ris_agent_createdrs$-//2K2M2MMJ Z ''rc >ddddddttddd S)NrF) r?r@r3r4rAr5 created_atstatepinned archived_at)r$ STATE_ACTIVErrr _empty_recordrs3jj   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.rFrGzFailed to read %s: %sN) rrKrarbrMrRrfrSrTrcrditemsr)pathrhrYcleanr_vs r load_usagers ==D ;;== z$..'.::;; T) * ,dA666  dD ! ! ')E 1 a   E#a&&M Ls(AB %BB B rhNonect} |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.Tparentsexist_okz.usage_z.tmp)dirprefixsuffixwrFrGF)indent sort_keys ensure_asciiNzFailed to write %s: %sexc_info)rrvmkdirtempfilemkstemprosfdopenradumpflushfsyncfilenor, BaseExceptionunlinkrR ExceptionrSrT)rhrfdtmp_pathfrYs 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.)rr6rcrdrr setdefault)rrhrecryr_rs r get_recordrsx <Load, apply *mutator(record)* in place, save. Best-effort. Bundled and hub-installed skills are NEVER recorded in the sidecar. This keeps .usage.json focused on agent-created skills (the only ones the curator considers) and prevents stale counters from hanging around for upstream-managed skills. Nz"skill_usage._mutate(%s) failed: %sTr) rrr6rcrdrrrrSrT)rmutatorrhrrYs r_mutaters  Y ++  F||hhz""#t$$ "//C Z4 YYY 9:qSW XXXXXXXXXYsA>A%A>> B1B,,B1c.dd}t||dS)z=Bump view_count and last_viewed_at. Called from skill_view().rr0rrc|t|dpddz|d<t|d<dS)Nr@rrJr4r=r6r$rs r_applyzbump_view.._apply<s? 5 5 :;;a?L (  rNrr0rrrrrs 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).rr0rrc|t|dpddz|d<t|d<dS)Nr?rrJr3rrs rrzbump_use.._applyEs>sww{338q99A=K&jjNrNrrrs rbump_userBs.)))) Jrc.dd}t||dS)zLBump patch_count and last_patched_at. Called from skill_manage (patch/edit).rr0rrc|t|dpddz|d<t|d<dS)NrArrJr5rrs rrzbump_patch.._applyMs? !7!7!<1==AM!) rNrrrs r bump_patchrKs.,,,, Jrrctvrtd|dSdfd }t||dS) z1Set lifecycle state. No-op if *state* is invalid.z"set_state: invalid state %r for %sNrr0rrcr|d<tkrt|d<dStkrd|d<dSdS)Nrr)STATE_ARCHIVEDr$r)rrs rrzset_state.._applyXsNG N " "!)C    l " "!%C   # "rr) _VALID_STATESrSrTr)rrrs ` r set_staterSs` M!! 95*MMM&&&&&&  Jrrc4dfd }t||dS)Nrr0rrc,t|d<dS)Nr)r)rrs rrzset_pinned.._applybsV H rrr)rrrs ` r set_pinnedras7%%%%%% Jrc|sdS t}||vr||=t|dSdS#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)rrrrSrT)rrhrYs rforgetrgs X||   Z t        XXX 8*aRV WWWWWWWWWXs$. A!AA!Tuple[bool, str]ct|sdd|dfSt|}|dd|dfSt} |ddn#t$r}dd|fcYd}~Sd}~wwxYw||jz }|r>||jd tjtj  d z } | |np#t$rc}d dl } |t|t|n##t $r}dd |fcYd}~cYd}~Sd}~wwxYwYd}~nd}~wwxYwt#|t$dd |fS)uMove an agent-created skill directory to ~/.hermes/skills/.archive/. Returns (ok, message). Never archives bundled or hub skills — callers are responsible for checking provenance, but we double-check here as a safety net. Fskill 'z,' is bundled or hub-installed; never archiveNz ' not foundTrzfailed to create archive dir: -z %Y%m%d%H%M%Srzfailed to archive: z archived to )r_find_skill_dirrrrRrXrKrr!rr"strftimerenameshutilmoverrrr)r skill_dir archive_rootrYdestre2s r archive_skillrxs  J ' 'YX XXXXX ++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 5j.))) &&& &&slA A3"A.(A3.A3C)) E3E80D)(E) E 3E9E :E>EE  EEctsdddfSt}|sdSfd|dD}|s0t fd|dDd }|sddd fS|d }t z }|rdd |fS ||nf#t$rYd d l} | t|t|n #t$r}dd|fcYd }~cYSd }~wwxYwYnwxYwttdd|fS)uMove 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 bundled or hub-installed skill — that would shadow the upstream version. FrzL' is now bundled or hub-installed; restore would shadow the upstream version)Fzno archive directorycRg|]#}||jk!|$Sr)is_dirrXr^prs r z!restore_skill..s3\\\ \qvQ[G[G[!G[G[G[r*cvg|]5}||jd3|6S)r)rrXrtrs rrz!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 )rrrKrqrxrrrRrrrrrr)rr candidatessrcrrrYs` r restore_skillrs J ' '  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 - ,4j,''' &&& &&sBC%%E40D%$E% E/D=5E6E=EEEOptional[Path]clt}|sdS|dD]y} ||}n#t$rY%wxYw|jr!|jddrQt||jj |kr |jcSzdS)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. Nrlrrmro) rrKrqrrr+rsrtrurvrX)rryr}r~s rrrs ==D ;;==tJJz**## &&t,,CC    H  9 10055   Hx/C D D D R R? " " " S 4sA A A List[Dict[str, Any]]ct}g}tD]}||}t|tst }t }|D]\}}|||d|i|}t||d<t||d<| ||S)zReturn a list of {name, state, pinned, last_activity_at, ...} records for every agent-created skill. Missing usage records are backfilled with defaults so callers can always index fields.rXlast_activity_atrC) rrr6rcrdrrrr<rCrw)rhrowsrXrryr_rrows ragent_created_reportrs <rs.#"""""  ''''''''BBBBBBBBBBBBBBBBBB,,,,,,  8 $ $  {N; (((())))&&&&2222    (.&@*((((    (GGGG0    YYYY8                     X X X X"$'$'$'$'N.'.'.'.'b2r