
    iGT                       d Z ddlmZ ddlZddlZddlZddlZddlmZ ddl	m	Z	m
Z
 ddlmZ ddlmZmZmZmZmZmZmZ ddlmZ  ej        e          ZdZ	 ddlZn# e$ r dZ	 ddlZn# e$ r Y nw xY wY nw xY wd	Zd
ZdZeeehZ dCdZ!dCdZ"ed             Z#dCdZ$dDdZ%dEdZ&dFdZ'dGdZ(dHdZ)dHd Z*dId"Z+dId#Z,dJd&Z-dKd)Z.dLd*Z/dMd+Z0dNd-Z1dOd0Z2dPd1Z3dQd2Z4dQd3Z5dQd4Z6dQd5Z7dQd6Z8dRd8Z9dSd:Z:dQd;Z;dTd=Z<dTd>Z=dUd@Z>dVdBZ?dS )Wa  Skill 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)datetimetimezone)Path)AnyDictIterableListOptionalSetTupleget_hermes_homeactivestalearchivedreturnr   c                 $    t                      dz  S )Nskillsr        6/home/piyush/.hermes/hermes-agent/tools/skill_usage.py_skills_dirr   :   s    x''r   c                 $    t                      dz  S )Nz.usage.jsonr   r   r   r   _usage_filer   >   s    ===((r   c               #    K   t                                          d          } | j                            dd           t          t
          dV  dS t
          rH|                                 r|                                 j        dk    r| 	                    dd           t          | t
          rd	nd
          }	 t          r t	          j        |t          j                   nG|                    d           t          j        |                                t
          j        d           dV  t          r t	          j        |t          j                   ngt
          r`	 |                    d           t          j        |                                t
          j        d           n# t&          t(          f$ r Y nw xY w|                                 dS # t          r t	          j        |t          j                   ngt
          r`	 |                    d           t          j        |                                t
          j        d           n# t&          t(          f$ r Y nw xY w|                                 w xY w)z@Serialize .usage.json read-modify-write cycles across processes.z
.json.lockTparentsexist_okNr    utf-8encodingzr+za+   )r   with_suffixparentmkdirfcntlmsvcrtexistsstatst_size
write_textopenflockLOCK_EXseeklockingfilenoLK_LOCKLOCK_UNLK_UNLCKOSErrorIOErrorclose)	lock_pathfds     r   _usage_file_lockr>   B   s7      )),77I4$777} 4y'')) 4Y^^-=-=-E-J-JS7333	i1T	2	2B 	;KEM****GGAJJJN299;;::: 	KEM**** 	


ryy{{FOQ????W%   





  	KEM**** 	


ryy{{FOQ????W%   




sE   =A2G AF& &F:9F:/I7AI
I7II7II7c                 $    t                      dz  S )Nz.archiver   r   r   r   _archive_dirr@   c   s    ==:%%r   strc                 b    t          j        t          j                                                  S )N)r   nowr   utc	isoformatr   r   r   _now_isorF   g   s     <%%//111r   valuer   Optional[datetime]c                    | sdS 	 t          j        t          |                     }n# t          t          f$ r Y dS w xY w|j         |                    t          j                  }|S )z<Parse an ISO timestamp defensively for activity comparisons.N)tzinfo)	r   fromisoformatrA   	TypeError
ValueErrorrJ   replacer   rD   )rG   parseds     r   _parse_iso_timestamprP   k   su     t'E

33z"   tt}x|44Ms   !( ==recordDict[str, Any]Optional[str]c                    d}d}dD ]B}|                      |          }t          |          }|)|||k    r|}t          |          }C|S )a(  Return the newest actual activity timestamp for a usage record.

    "Activity" means a skill was used, viewed, or patched. Creation time is
    intentionally excluded so callers can still distinguish never-active skills;
    lifecycle code can fall back to ``created_at`` as its own anchor.
    N)last_used_atlast_viewed_atlast_patched_at)getrP   rA   )rQ   	latest_dt
latest_rawkeyrawdts         r   latest_activity_atr^   x   sf     %)I $JD " "jjoo!#&&:YISJr   intc                    d}dD ]A}	 |t          |                     |          pd          z  }+# t          t          f$ r Y >w xY w|S )zFReturn the total observed activity count across use/view/patch events.r   )	use_count
view_countpatch_count)r_   rX   rL   rM   )rQ   totalr[   s      r   activity_countre      sh    E9  	SC-A...EE:& 	 	 	H	Ls   '0AASet[str]c                    t                      dz  } |                                 st                      S t                      }	 |                     d                                          D ]^}|                                }|s|                    dd          d                                         }|r|                    |           _n2# t          $ r%}t          
                    d|           Y d}~nd}~ww xY w|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&   r   z#Failed to read bundled manifest: %sN)r   r,   set	read_text
splitlinesstripsplitaddr9   loggerdebug)manifestnameslinenamees        r   _read_bundled_manifest_namesrv      s    }}22H?? uueeE	?&&&88CCEE 	  	 D::<<D ::c1%%a(..00D  		$	   ? ? ?:A>>>>>>>>?Ls   BC 
C:C55C:c                    t                      dz  dz  } |                                 st                      S 	 t          j        |                     d                    }t          |t                    r|                    d          pi }t          |t                    rZd |	                                D             }t                      }|
                                D ]}t          |t                    s|                    d          }t          |t                    r|                                sXt          |          }|                                s||z  }	 |                                }|                    |                                           n# t"          t$          f$ r Y w xY w|dz  }	|	                                r)|                    t)          |	|j        	                     |S n># t"          t          j        f$ r%}
t.                              d
|
           Y d}
~
nd}
~
ww xY wt                      S )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          |          S r   )rA   ).0ks     r   	<setcomp>z,_read_hub_installed_names.<locals>.<setcomp>   s    :::AQ:::r   install_pathSKILL.mdfallbackz Failed to read hub lock file: %sN)r   r,   ri   jsonloadsrj   
isinstancedictrX   keysvaluesrA   rl   r   is_absoluteresolverelative_tor9   rM   rn   _read_skill_namert   JSONDecodeErrorro   rp   )r<   datarx   rr   
skills_direntryr}   	skill_dirresolvedskill_mdru   s              r   _read_hub_installed_namesr      sG   
 &4I uu<z)--w-??@@dD!! 	--3I)T** ::)9)9:::(]]
&--// V VE%eT22 ! #(99^#<#<L%lC88 !@R@R@T@T !  $\ 2 2I$0022 ;$.$:	!#,#4#4#6#6 ,,Z-?-?-A-ABBBB#Z0 ! ! ! !'*4H(( V		"28hm"T"T"TUUUT)* < < <7;;;;;;;;<55Ls=   D+G> $;F G>  F41G> 3F44AG> >H9H44H9	List[str]c                 t   t                      } |                                 sg S t                      }t                      }||z  }t	                      }g }|                     d          D ]}	 |                    |           }n# t          $ r Y %w xY w|j        }|r(|d         	                    d          s|d         dk    rZt          ||j        j                  }	|	|v rzt          |                    |	                    s|                    |	           t!          t#          |                    S )a  Enumerate skills explicitly authored by the agent.

    The curator operates exclusively on this set. Skills are only eligible
    after ``skill_manage(action="create")`` marks them in ``.usage.json``;
    manually authored skills must not be inferred from filesystem location.
    Bundled / hub skills are maintained by their upstream sources and must
    never be pruned here.
    r~   r   .node_modulesr   )r   r,   rv   r   
load_usagerglobr   rM   parts
startswithr   r(   rt   _is_curator_managed_recordrX   appendsortedri   )
basebundledhub
off_limitsusagerr   r   relr   rt   s
             r   list_agent_created_skill_namesr      sH    ==D;;== 	*,,G
#
%
%C3JLLEEJJz**  	&&t,,CC 	 	 	H		 	eAh))#.. 	%(n2L2L8?3GHHH:)%))D//:: 	T#e**s   .B
BBc                     t                      } |                                 sg S t          d |                                 D                       S )a  Enumerate skills in ``~/.hermes/skills/.archive/``.

    Archive layout is flat (``.archive/<skill>/``) 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``.
    c                D    h | ]}|                                 |j        S r   is_dirrt   )rz   ps     r   r|   z,list_archived_skill_names.<locals>.<setcomp>  s'    HHHaQXXZZH16HHHr   )r@   r,   r   iterdir)archive_roots    r   list_archived_skill_namesr      sO      >>L   	HH<#7#7#9#9HHHIIIr   r   r   c                   	 |                      dd          dd         }n# t          $ r |cY S w xY wd}|                    d          D ]}|                                }|dk    r|r nbd	}#|r\|                    d
          rG|                    dd          d                                                             d          }|r|c S |S )z9Parse the `name:` field from a SKILL.md YAML frontmatter.r#   rN   )r%   errorsNi  F
z---Tzname:rh   r&   z"')rj   r9   rm   rl   r   )r   r   textin_frontmatterrs   strippedrG   s          r   r   r   
  s   !!79!EEeteL   N

4   
 
::<<u !N 	h11':: 	NN3**1-3355;;EBBE Os   " 11
skill_nameboolc                D    t                      t                      z  }| |vS )z:Whether *skill_name* is neither bundled nor hub-installed.)rv   r   )r   r   s     r   is_agent_createdr     s$    -//2K2M2MMJZ''r   c                    t          | t                    sdS |                     d          dk    p|                     d          du S )zEReturn True when a usage record opts a skill into curator management.F
created_byagentagent_createdT)r   r   rX   )rQ   s    r   r   r   %  sG    fd## u::l##w.U&**_2M2MQU2UUr   c                 @    d ddd d dd t                      t          dd dS )Nr   F)r   ra   rb   rU   rV   rc   rW   
created_atstatepinnedarchived_at)rF   STATE_ACTIVEr   r   r   _empty_recordr   0  s6    jj  r   Dict[str, Dict[str, Any]]c                    t                      } |                                 si S 	 t          j        |                     d                    }nA# t
          t          j        f$ r(}t                              d| |           i cY d}~S d}~ww xY wt          |t                    si S i }|                                D ],\  }}t          |t                    r||t          |          <   -|S )zGRead the entire .usage.json map. Returns empty dict on missing/corrupt.r#   r$   zFailed to read %s: %sN)r   r,   r   r   rj   r9   r   ro   rp   r   r   itemsrA   )pathr   ru   cleanr{   vs         r   r   r   @  s    ==D;;== 	z$..'.::;;T)*   ,dA666						 dD!! 	')E

  1a 	E#a&&MLs   (A B%BBBr   Nonec                   t                      }	 |j                            dd           t          j        t          |j                  dd          \  }}	 t          j        |dd          5 }t          j	        | |d	dd
           |
                                 t          j        |                                           ddd           n# 1 swxY w Y   t          j        ||           dS # t          $ r( 	 t          j        |           n# t           $ r Y nw xY w w xY w# t"          $ r)}t$                              d||d           Y d}~dS d}~ww xY w)uN   Write the usage map atomically. Best-effort — errors are logged, not raised.Tr   z.usage_z.tmp)dirprefixsuffixwr#   r$      F)indent	sort_keysensure_asciiNzFailed to write %s: %sexc_info)r   r(   r)   tempfilemkstemprA   osfdopenr   dumpflushfsyncr5   rN   BaseExceptionunlinkr9   	Exceptionro   rp   )r   r   r=   tmp_pathfru   s         r   
save_usager   T  s   ==DG$666'DK  6
 
 
H	2sW555 %	$!t%PPPP			$$$% % % % % % % % % % % % % % % Jx&&&&& 	 	 		(####   	  G G G-tQFFFFFFFFFGss   AD' C2 0ACC2 CC2 CC2 2
D$=DD$
DD$DD$$D' '
E1EEc                   t                      }|                    |           }t          |t                    st	                      S t	                      }|                                D ]\  }}|                    ||           |S )zDReturn the record for *skill_name*, creating a fresh one if missing.)r   rX   r   r   r   r   
setdefault)r   r   recr   r{   r   s         r   
get_recordr   l  sx    <<D
((:

Cc4   ??D

  1q!Jr   c                   | sdS 	 t          |           sdS t                      5  t                      }|                    |           }t	          |t
                    st                      } ||           ||| <   t          |           ddd           dS # 1 swxY w Y   dS # t          $ r)}t          
                    d| |d           Y d}~dS d}~ww xY w)a  Load, apply *mutator(record)* in place, save. Best-effort.

    Bundled and hub-installed skills are NEVER recorded in the sidecar.
    Local manual skills may still accrue usage telemetry, but they only
    become curator-managed when ``created_by`` is explicitly marked.
    Nz"skill_usage._mutate(%s) failed: %sTr   )r   r>   r   rX   r   r   r   r   r   ro   rp   )r   mutatorr   r   ru   s        r   _mutater   y  sI     Y
++ 	F 	 	<<D((:&&Cc4(( &#ooGCLLL"Dt	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	  Y Y Y9:qSWXXXXXXXXXYs@   B% B% A&BB% BB% B B% %
C/CCc                .    dd}t          | |           dS )z=Bump view_count and last_viewed_at. Called from skill_view().r   rR   r   r   c                |    t          |                     d          pd          dz   | d<   t                      | d<   d S )Nrb   r   r&   rV   r_   rX   rF   r   s    r   _applyzbump_view.<locals>._apply  s?     5 5 :;;a?L (

r   Nr   rR   r   r   r   r   r   s     r   	bump_viewr     s.    + + + + Jr   c                .    dd}t          | |           d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).r   rR   r   r   c                |    t          |                     d          pd          dz   | d<   t                      | d<   d S )Nra   r   r&   rU   r   r   s    r   r   zbump_use.<locals>._apply  s>    sww{338q99A=K&jjNr   Nr   r   r   s     r   bump_user     s.    ) ) ) ) Jr   c                .    dd}t          | |           dS )zLBump patch_count and last_patched_at. Called from skill_manage (patch/edit).r   rR   r   r   c                |    t          |                     d          pd          dz   | d<   t                      | d<   d S )Nrc   r   r&   rW   r   r   s    r   r   zbump_patch.<locals>._apply  s?     !7!7!<1==AM!)r   Nr   r   r   s     r   
bump_patchr     s.    , , , , Jr   c                .    dd}t          | |           dS )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.
    r   rR   r   r   c                    d| d<   d S )Nr   r   r   r   s    r   r   z"mark_agent_created.<locals>._apply  s    #Lr   Nr   r   r   s     r   mark_agent_createdr     s,    $ $ $ $Jr   r   c                    t           vrt                              d|            dS dfd}t          | |           dS )	z1Set lifecycle state. No-op if *state* is invalid.z"set_state: invalid state %r for %sNr   rR   r   r   c                r    | d<   t           k    rt                      | d<   d S t          k    rd | d<   d S d S )Nr   r   )STATE_ARCHIVEDrF   r   )r   r   s    r   r   zset_state.<locals>._apply  sN    GN""!)Cl""!%C #"r   r   )_VALID_STATESro   rp   r   )r   r   r   s    ` r   	set_stater     s`    M!!95*MMM& & & & & & Jr   r   c                4    dfd}t          | |           d S )Nr   rR   r   r   c                ,    t                    | d<   d S )Nr   )r   )r   r   s    r   r   zset_pinned.<locals>._apply  s    VHr   r   r   )r   r   r   s    ` r   
set_pinnedr    s7    % % % % % %Jr   c                   | sdS 	 t                      5  t                      }| |v r|| = t          |           ddd           dS # 1 swxY w Y   dS # t          $ r)}t                              d| |d           Y d}~dS d}~ww xY w)zFDrop a skill's usage entry entirely. Called when the skill is deleted.Nz!skill_usage.forget(%s) failed: %sTr   )r>   r   r   r   ro   rp   )r   r   ru   s      r   forgetr    s    X 	! 	!<<DT!!$4   		! 	! 	! 	! 	! 	! 	! 	! 	! 	! 	! 	! 	! 	! 	! 	! 	! 	!
  X X X8*aRVWWWWWWWWWXs9   A %AA A

A A
A 
BBBTuple[bool, str]c                   t          |           sdd|  dfS t          |           }|dd|  dfS t                      }	 |                    dd           n# t          $ r}dd| fcY d}~S d}~ww xY w||j        z  }|                                r>||j         d	t          j        t          j
                                      d
           z  }	 |                    |           np# t          $ rc}ddl}	 |                    t          |          t          |                     n## t           $ r}dd| fcY d}~cY d}~S d}~ww xY wY d}~nd}~ww xY wt#          | t$                     dd| fS )u   Move 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.
    Fskill 'z,' is bundled or hub-installed; never archiveNz' not foundTr   zfailed to create archive dir: -z%Y%m%d%H%M%Sr   zfailed to archive: zarchived to )r   _find_skill_dirr@   r)   r9   rt   r,   r   rC   r   rD   strftimerenameshutilmoverA   r   r   r   )r   r   r   ru   destr  e2s          r   archive_skillr    s
    J'' YX
XXXXX
++I7
77777>>L;4$7777 ; ; ;:q:::::::::;
 ).(D{{}} hgg(,x|2L2L2U2UVd2e2eggg5 5 5 5	5KKID		2222 	5 	5 	5444444444444444	5 32222	5 j.)))&&&&&sl    A 
A3"A.(A3.A3C) )
E3E80D)(E)
E	3E9E	:E>EE		EEc                    t                     sdd  dfS t                      }|                                sdS  fd|                    d          D             }|s0t	           fd|                    d          D             d	          }|sdd  d
fS |d         }t                       z  }|                                rdd| fS 	 |                    |           nf# t          $ rY ddl}	 |	                    t          |          t          |                     n # t          $ r}dd| fcY d}~cY S d}~ww xY wY nw xY wt           t                     dd| fS )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 bundled or
    hub-installed skill — that would shadow the upstream version.
    Fr  zL' is now bundled or hub-installed; restore would shadow the upstream version)Fzno archive directoryc                R    g | ]#}|                                 |j        k    !|$S r   r   rz   r   r   s     r   
<listcomp>z!restore_skill.<locals>.<listcomp>  s3    \\\

\qvQ[G[G[!G[G[G[r   *c                v    g | ]5}|                                 |j                             d           3|6S )r  )r   rt   r   r  s     r   r  z!restore_skill.<locals>.<listcomp>  s^     D D D1

D v00J1A1A1ABBDQ D D Dr   T)reversez' not found in archiver   zdestination already exists: Nzfailed to restore: zrestored to )r   r@   r,   r   r   r   r
  r9   r  r  rA   r   r   r   )r   r   
candidatessrcr  r  ru   s   `      r   restore_skillr    s    J'' 
8j 8 8 8
 	
  >>L   -,,
 ]\\\\//44\\\J 
D D D D**3// D D D
 
 


  CB
BBBBB
Q-C==:%D{{}} <;T;;;;4

4 4 4 4	4KKC#d)),,,, 	4 	4 	4333333333333	4 -,4 j,'''&&&&&sB   C% %E40D%$E%
E/D=5E6E=EEEOptional[Path]c                l   t                      }|                                sdS |                    d          D ]y}	 |                    |          }n# t          $ r Y %w xY w|j        r!|j        d                             d          rQt          ||j        j	                  | k    r	|j        c S zdS )zLocate the directory for a skill by its frontmatter `name:` field.

    Handles both flat (~/.hermes/skills/<skill>/SKILL.md) and category-nested
    (~/.hermes/skills/<category>/<skill>/SKILL.md) layouts.
    Nr~   r   r   r   )
r   r,   r   r   rM   r   r   r   r(   rt   )r   r   r   r   s       r   r  r  7  s     ==D;;== tJJz** # #	&&t,,CC 	 	 	H	9 	10055 	Hx/CDDD
RR?""" S4s   A
A A List[Dict[str, Any]]c                    t                      } g }t                      D ]}|                     |          }t          |t                    st                      }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.rt   last_activity_atre   )r   r   rX   r   r   r   r   r   r^   re   r   )r   rowsrt   r   r   r{   r   rows           r   agent_created_reportr!  P  s     <<D!#D.00 
 
hhtnn#t$$ 	"//CJJLL 	! 	!DAqNN1a    t#s#"4S"9"9 .s 3 3CKr   )r   r   )r   rA   )rG   r   r   rH   )rQ   rR   r   rS   )rQ   rR   r   r_   )r   rf   )r   r   )r   r   r   rA   r   rA   )r   rA   r   r   )rQ   r   r   r   )r   rR   )r   r   )r   r   r   r   )r   rA   r   rR   )r   rA   r   r   )r   rA   r   rA   r   r   )r   rA   r   r   r   r   )r   rA   r   r  )r   rA   r   r  )r   r  )@__doc__
__future__r   r   loggingr   r   
contextlibr   r   r   pathlibr   typingr   r	   r
   r   r   r   r   hermes_constantsr   	getLogger__name__ro   r+   r*   ImportErrorr   STATE_STALEr   r   r   r   r>   r@   rF   rP   r^   re   rv   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r  r  r  r  r  r!  r   r   r   <module>r-     s   0 # " " " " "   				  % % % % % % ' ' ' ' ' ' ' '       B B B B B B B B B B B B B B B B B B , , , , , ,		8	$	$ 
LLLL   E   	 {N;( ( ( () ) ) )   @& & & &2 2 2 2
 
 
 
   (      .# # # #L" " " "J
J 
J 
J 
J   *( ( ( (V V V V       (G G G G0
 
 
 
Y Y Y Y8                                          X X X X$$' $' $' $'N.' .' .' .'b   2     s6   A A8%A*)A8*A2/A81A22A87A8