yj>BUdZddlmZddlZddlZddlZddlZddlmZddl 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<dudZ%dvdZ&dvdZ'edZ(dvdZ)dwdZ*dxdZ+dyd"Z,dzd$Z-d{d%Z.d{d&Z/d|d'Z0dvd(Z1d{d)Z2d}d,Z3d~d-Z4d~d.Z5dd0Z6dd1Z7dd4Z8dud5Z9dud6Z:dud7Z;dd8Zdud=Z?dd>Z@dd@ZAddBZBddCZCddEZDddGZEddHZFd~dIZGdJdKddMZHddNZI dddPZJdddddddQddZZKd~d[ZLddd\dd]ZMd^ddd_dd`ZNddd\ddbZOd~dcZPd~ddZQddfZRddhZSddjZTdudkZUd~dlZVddmZWddnZXddoZYddpZZddqZ[ddrZ\ddsZ]ddtZ^dS)aSkill 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/ragecks/.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|dd}t |tr|dpi}t |trZd| D}t}| D]}t |ts|d}t |tr| sXt|}|s||z } |}||n#t"t$f$rYwxYw|d z } | 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-rXr/errors 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_namesrsK  &4I     uu "<z)--wy-QQRR dD ! ! --3I)T** ::)9)9:::(]] &--//VVE%eT22! #(99^#<#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_namer>sS  ! # #E *&&&&&r c~|sdSt}||vr&||t|dSdS)z7Clear a built-in's suppression entry (e.g. on restore).N)rdiscardrrs rremove_suppressed_namerHsS  ! # #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_namesrRsy ==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-rXrNiFrz---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. Org-shared skills ARE eligible for improvement (the curator may patch them like any other skill; edits stay local until proposed) but are protected from ARCHIVE/DELETE elsewhere — removing a shared skill is an org-admin action, not a local curation decision. 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)uReturn True when a usage record opts a skill into curator management. NAMING (issue #67140): the on-disk field is ``created_by``, which reads like provenance but is consumed as a **curator-management opt-in policy flag**. The two are not the same question: * provenance = "who authored this file" — historical fact, and for records written before the marker existed it is simply unrecoverable. * management = "may autonomous curation mutate/archive this" — a policy decision the user can change at any time via ``hermes curator adopt``. ``created_by: "agent"`` therefore means "curator-managed", NOT "proof the agent wrote it". The field name is retained because it is already on disk in every user's ``.usage.json``; renaming it would strand those records. Read it as policy, and prefer ``is_curator_managed()`` at call sites so the intent is unambiguous. F created_byagent agent_createdT)rrrbr[s rrrsI$ fd # #u ::l # #w . U&**_2M2MQU2UUr c^tt|S)aWhether *skill_name* is opted into curator management. Policy-intent alias for the ``created_by``-marker check, so call sites read as the question they are actually asking (see ``_is_curator_managed_record`` for why the stored field name says "created_by"). )rrrbrs ris_curator_managedrs$ &jll&6&6z&B&B C CCr ct}|sgSt}t}t }g}|dD]}t |st|r! ||n#t$rYDwxYwt||j j }||vs||vst|r{t||rt!||s||t%t'|S)uEnumerate curation-ELIGIBLE skills that carry no provenance marker. These are skills the curator *could* manage (they are not hub-installed, not external, not protected built-ins) but never will, because nothing ever wrote ``created_by: agent`` onto their usage record. Two ways a skill lands here: * It predates the provenance mechanism entirely — records written before ``created_by`` existed carry no key at all, so their authorship is unknowable from the record alone. * It was created by a FOREGROUND ``skill_manage(action="create")`` call, which deliberately does not mark provenance (skills a user asks for belong to the user). Either way the skill is invisible to ``curated_report()`` and therefore to every automatic transition. ``hermes curator status`` surfaces this count so the blind spot is legible instead of silent, and ``hermes curator adopt`` lets the user hand specific skills over explicitly. Provenance is a DECLARATION, never an inference: this function only reports, and callers must not auto-adopt what it returns. Heavy patch or use counts are evidence of maintenance, not of authorship — the agent edits user-authored skills on the user's behalf routinely. rr)r$r6rrrrrrrrWrr2r}rrrbrrrrr)rrrrr{rr}s rlist_unmanaged_skill_namesrsU2 ==D ;;== # % %C*,,G LLEEJJz** !( + + /Eh/O/O      & & & &    H 8?3GHHH 3;;$'//-A$-G-G/  %eiioo 6 6  #D(33   T #e**  sB B+*B+List[Dict[str, Any]]c4t}g}tD]}||}t|trt |n t }t D]\}}|||d|i|}t|tod|v|d<t|t|d<t||d<t||d<| ||S)aRows for every skill :func:`list_unmanaged_skill_names` returns. Each row carries the usual activity fields plus ``has_provenance_key``: False when the record has no ``created_by`` key at all (pre-dates the mechanism), True when the key is present but unset (a foreground create under the current policy). The distinction matters for explaining WHY a skill is unmanaged; it is not a signal to adopt on. r}rhas_provenance_key has_recordlast_activity_atro) rrrbrr _empty_recorditems setdefaultrhror)rrowsr}rfrecrvrows runmanaged_reportr ;s LLE!#D*,,  iioo+5c4+@+@Ud3iiimoo!OO))++ ! !DAq NN1a t#s#$.sD$9$9$Qlc>Q !&sD11L"4S"9"9  .s 3 3  C Kr Tuple[bool, str]c>|sdSt|rdd|dfSt|rdd|dfSt|rdd|dfSt|}|t |dd|dfSdd |d fSt |rdt |fSt}t| |rd d|d fSt|tt |sdd |dfSd d|dfS)uwHand *skill_name* to the curator by user declaration. Writes the same ``created_by: agent`` marker the background review fork writes, so the skill joins ``curated_report()`` and the automatic transition walk. The inactivity clock is NOT reset: the skill's existing ``last_activity_at`` still governs staleness, so adopting something idle for months does not buy it a fresh window (nor does it archive it on the spot — the state machine decides on the next pass). Returns (ok, message). Refuses hub-installed, external, and protected built-in skills, which have an owner other than the user. )Fzno skill name givenF'z7' is a protected built-in; the curator never manages itz(' is hub-installed; its upstream owns ituU' is a bundled built-in — it is governed by curator.prune_builtins, not by adoptionNz?' lives in skills.external_dirs and is read-only to the curatorr ' not foundTz' is already curator-managedzcould not mark 'z' as curator-managedz adopted 'z' into curator management) rrrrrrrrrrbmark_agent_created)rrrs r adopt_skillrTs ,++J''^]*]]]]] ##ON*NNNNN*  6  6 6 6   ++I #J / / ;ijiiii i7 77777i((>1*==== LLE!%))J"7"788BAAAAAAz""" %jll&6&6z&B&B C CJIIIIII BZBBB BBr cDdddddddddttddd S)NrF) rrkrlr_r`rmpatch_generationlast_reused_patch_generationra created_atstatepinned archived_at)rP STATE_ACTIVEr#r rrrs<()jj  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'r6rrrsrBrrxryrrrr)rrr~cleanrr s 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 ||dS#t$r( t j|n#t $rYnwxYwwxYw#t"$r)}t$d ||dYd }~d Sd }~wwxYw)z?Write the usage map atomically and report whether it committed.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 ==D $666'DK  6   H 2sW555 % $!t%PPPP $$$ % % % % % % % % % % % % % % % Jx & & &4     (####         -tQ FFFuuuuussAD'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.)rrbrrrrr)rrrrrr s r get_recordr&sx <._applyZs:-cggl.C.CDDqHL (  r Nrr\rrr/rrOs r bump_viewrSTs. ++++ Jr )r=r>c d d}t||}t|tr+t|d||||d|d|d d Sd S) 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\rct|d}t|d}tt|d|}|dk}|o||k}|dz|d<t|d<||d<||d<|r||d<|d|d||dS) Nrkrrrr0r_r)rrkr?r@)r2rbminrP)rprevious_use_countrlast_reused_generationr?r@s rrOzbump_use.._applyks.sww{/C/CDD,SWW5G-H-HII!$ cgg&DEE F F " " $a'"P'7:P'P-1K&jjN"2 .D *+  C2BC. /'',//[)!2    r loadedrkr?r@r<Nrr\rr\r/rrrJ)rr=r>rOfactss rbump_user]`s    , J ' 'E%    !K(?#$78    r patch)rAr=r>c|dkrdnd}d d}t||}t|trt|||||d Sd S) zBump patch_count and last_patched_at. Called from skill_manage (patch/edit). Tracks every skill regardless of provenance. r^patchededitedrr\rct|ddz|d<t|ddz|d<t|d<d|diS)Nrmr0rrarrMrNs rrOzbump_patch.._applysq.sww}/E/EFFJM"3CGGNrZr[)rrAr=r>lifecycle_actionrOr\s r bump_patchres%+g$5$5yy85555 J ' 'E%   !         r rcdfd }t||}t|trt|d|||dSdS) zGPersist explicit creation provenance and emit a successful create fact.rr\rc||trd|d<d|diSNrr)clearupdater)rrs rrOzrecord_created.._applysJ  =??###  ( 'C c,/00r createdrcNrZr[)rrr=r>rOr\s ` rrecord_createdrls~111111 J ' 'E%   !         r cdd}t||}t|trt|d|dSdS) zBRecord a successful Skills Hub install without exporting its name.rr\rc>d|d<t|d<d|d<d|diS)Nrrrr)rrNs rrOz record_installed.._applys/'L#G !Mc,/00r rrNrZr[)rrOr\s rrecord_installedrosa1111 J ' 'E%Ej+eDDDDDDEEr 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<dSrhr#rNs rrOz"mark_agent_created.._applys#Lr Tr*NrPrQrRs rrrs1 $$$$ J$??????r rctvrtd|dSdfd }t||d}t |t r|d sdStd td i}tkr |d tkrd }|t|||dSdS)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\rc|d}|krd|ddS|d<tkrt|d<ntkrd|d<d|d|dS)NrFr)changedrrT)rtrprevious_state)rbSTATE_ARCHIVEDrPr)rrurs rrOzset_state.._applys)) U " "$CGGL4I4IJJ JG N " "!)C   l " "!%C '',//,   r Tr*rtrrrurestoredrrZ) _VALID_STATESrxryr/rrrbrv STATE_STALErrJ)rrrOr\rAs ` r set_staterzs M!! 95*MMM        J$ G G GE eT " "%))I*>*> W c%jj  +;!._applysV H r Tr*rPrQ)rrrOs ` r set_pinnedr~s<%%%%%% J$??????r syncc8d fd }t||ddS) aSet the sync opt-in flag on a skill's usage record. Sync is OPT-IN: nothing propagates to the sync plane unless the user marks a skill with ``sync: true`` here. Sits alongside ``pinned``/``created_by`` on the ``.usage.json`` sidecar and is read by ``tools.skills_sync_client.list_synced_skill_names``. Gated on curation eligibility so bundled/hub/external skills (which never sync) can't be marked. Provisional per the M1-D default. rr\rrc,t|d<dS)Nrr})rrs rrOzset_sync.._applys4jjF r Tr*NrPrQ)rrrOs ` rset_syncr s<!!!!!! J$??????r cJt|dduS)zBWhether a skill is opted into sync (``sync: true`` in its record).rT)r&rbrs ris_sync_enabledrs# j ! ! % %f - - 55r 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$rrxryr(s rforgetrs X    ! !<||j d tj tjd z } ||nf#t$rYd dl} |t)|t)|n #t*$r}dd|fcYd}~cYSd}~wwxYwYnwxYwt-|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 itrTr)zfailed to create archive dir: -z %Y%m%d%H%M%Srzfailed to archive: z archived to )rrrrrrrrJr3rBr}r6rrMrrNstrftimerenameshutilmoverrrrrzrv)rlocal_skill_dirrrr~destre2s 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 5 3 2 5*(J''' j.))) &&& &&s`3C C&C!C&!C&EF?+0FF? F9&F4,F9-F?4F99F?>F?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 *rcg|]}|rr|jrXt|jtz dkX|jtd|S)N)rr}rlenisdigit)rrrs rrz!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$rrBrrrrrrzr)rr candidatessrcrrr~rs` @r restore_skillrlsw ##  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}|sdSddlm}||dD]:}t |rt ||jj|kr |jcS;dS)aWLocate 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. Uses the gated index iterator so M2 org mirrors resolve ONLY for the active org (stale ``_org//`` trees never match). Nr)iter_skill_index_filesrr)r$r6agent.skill_utilsrrrr2r})rrrrs rrrs ==D ;;==t888888**4<<## !( + +   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)rrr6rrrr2r})rrrrs rrrs555555##%%abb)''{{}}   :.. ' 'H%h// 8?3GHHHJVV&&&&&W ' 4r c t}g}tD]}||}t|t}t|tr|n t }t }|D]\}}|||d|i|d|i} t| | d<t| | d<t|| d<| | |S)aReturn a list of {name, provenance, state, pinned, last_activity_at, ...} records for every curator-managed skill. Missing usage records are backfilled with defaults so callers can always index fields. ``provenance`` is 'agent', 'bundled', or 'hub' (see :func:`provenance`). Bundled skills are only included when ``curator.prune_builtins`` is enabled. Hub-installed skills are never included. 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} _persistedrrorH) rrrbrrrrrrhrorHr) rrr}rf persistedrrrr r s rcurated_reportrs <zusage_report..<s air )re)r$r6rrrrrrr2r}rwrbrrrrrrHrhrorr) rrrseenrr}rfrrbase_recrr r s r usage_reportrs ==D ;;== <r]rkrBr?rCr@rCrr)rrr=r]r>r]rr) rrrArr=r]r>r]rr) rrrrr=r]r>r]rr)rrrrrr)rrrrrr)rrrrrr)rrrr)___doc__ __future__rrloggingrr contextlibrrrpathlibrtypingrr r r r r hermes_constantsrrrr getLogger__name__rxr5r4 ImportErrorrryrvrxr__annotations__rr$r'rHrJrPrZrhrorrrrrrrrrrrrrrrrrrrr rrrr$r&r)r/r2r;rJrSr]rerlrorrzr~rrrrrrrrrrHrr#r rrs0#"""""  %%%%%%''''''''8888888888888888,,,,,,LLLLLLLL  8 $ $  LLLL   E          {N;  & 2222(((())))   F&&&&2222    (.++++\*1111*WWWW,''''''''4444n J J J J*5555 8888 <VVVV.DDDD2222j2)C)C)C)C`$(4    hhhh,LQ>(,@(,! $#!(," " " " " " R     " $ , , , , , , d! $       D" $       8 E E E E@@@@@@@@D@@@@ @ @ @ @6666 X X X X$:':':':'zH'H'H'H'V*    &>    &1&1&1&1&1&1s6A$$A?,A10A?1A96A?8A99A?>A?