Yffjv0dZddlmZddlZddlZddlmZmZddlmZddl m Z d'd Z d(d Z d)dZ d)dZd)dZd)dZd)dZd)dZd)dZd)dZd)dZd)dZd*dZd)dZd)dZd)dZd)d Zd)d!Zd+d$Zd,d)d%Zed&krej edSdS)-u0CLI subcommand: `hermes curator `. Thin shell around agent/curator.py and tools/skill_usage.py. Renders a status table, triggers a run, pauses/resumes, and pins/unpins skills. This module intentionally has no side effects at import time — main.py wires the argparse subparsers on demand. ) annotationsN)datetimetimezone)Path)Optionalts Optional[str]returnstrc|sdS tj|}n&#ttf$rt |cYSwxYw|j |tj}tj tj|z }t| }|dkr|dS|dkr|dzdS|dkr|dzdS|dzd S) Nnevertzinfo<zs agoizm agoiQzh agozd ago) r fromisoformat TypeError ValueErrorr rreplacerutcnowint total_seconds)rdtdeltasecss 8/home/thesage/.hermes/hermes-agent/hermes_cli/curator.py_fmt_tsrs w  #B ' ' z "2ww y ZZx|Z , , L & & +E u""$$ % %D byy~~~ d{{"*#### e||$,%%%%em " " ""s  >>Nonecdddlm} |}n#t$rYdSwxYw|sdSt d|D}t ||z }t dt |dt d|t d|t d dS) uReport curation-eligible skills that carry no provenance marker. A skill only becomes curator-managed once ``created_by: agent`` lands on its usage record, which happens ONLY for background-review creations. Skills predating that marker, plus every foreground ``skill_manage(create)``, are eligible but unmanaged — no automatic transition ever considers them. Printing just the managed count made a large library look fully curated while a big slice was untouchable. r skill_usageNc3DK|]}|ddVdS)has_provenance_keyNget).0rs r z+_print_unmanaged_summary..9s4IIqQUU3G-H-HIIIIIIIz# unmanaged (no provenance marker): z totalz pre-dates marker z foreground-created uP never auto-staled or archived — `hermes curator adopt ` hands one over)toolsr!unmanaged_report Exceptionsumlenprint)r! unmanagedlegacy foregrounds r_print_unmanaged_summaryr4's"!!!!!0022   IIIIII I IFY&(J GY G G GHHH +6 + +,,, /: / /000  7s  ++rc( ddlm}ddlm}|}|}|dd}|d}|dpd}|d d}|r|sd n|rd nd } td | td|tdt|d|vr@| ^} } td| | D]} td| ntd||d} | r9t|  rdnd}td| || }|dzdkr|dkr|dzdn|d}td|td| dtd|dtd|rdnd |rdnd!|}|std"t#dSgggd#}g}d}d}|D]}|d$d%}||g||d&r||d'|d(d)}|d)kr|d*z }|d+kr|d*z }td,t)|d-|d.|d/d#D];}||g}td0|d1d2t)|<|r5td3t)|d4d5|t#t-|d%gd67dd8}|rtd9|D]}t|d:}td0|d'd;d<|d=dd>d?|d@dd>dA|dBdd>dC|dDdd>dE| |d%g}|rt-|dFdGHdd8}|r|dd=pddkrtdI|D]}t|d:}td0|d'd;d<|d=dd>d?|d@dd>dA|dBdd>dC|dDdd>dE| t-|dJ7dd8}|rtdK|D]}t|d:}td0|d'd;d<|d=dd>d?|d@dd>dA|dBdd>dC|dDdd>dE| dS)LNrcuratorr pausedF last_run_atlast_run_summaryz(none) run_countENABLEDPAUSEDDISABLED curator: z runs: z last run:  z last summary: z last_report_pathz (missing)z last report: dhz interval: every z stale after: zd unusedz archive after: z consolidate: onoffz$ (prune-only; LLM merge pass opt-in)z no curator-managed skills)activestalearchivedstaterHpinnedname provenanceagentr$bundledz curator-managed skills: z total (agent-created= bundled=) 10s z pinned (z): z, cZ|dp|dpdS)Nlast_activity_at created_atrBr%r(s rz_cmd_status..s)aee.//L1553F3FL"r*keyz least recently active (top 5):rW40sz activity=activity_count3dz use= use_countz view= view_countz patches= patch_count last_activity=c^|dpd|dpdfSNr_rrWrBr%rYs rrZz_cmd_status..0155!1227a?Q9R9R9XVXYr*Tr\reversez most active (top 5):c^|dpd|dpdfSrfr%rYs rrZz_cmd_status..rgr*z least active (top 5):)rOr7r+r! load_state is_enabledr&r0r splitlinesrexistsget_interval_hoursget_stale_after_daysget_archive_after_daysget_consolidatecurated_reportr4 setdefaultappendr/joinsorted)argsr7r!rKenabledr8last_runsummaryruns status_linefirstrestline_reportsuffix_ih_interval_labelrowsby_staterL agent_count bundled_countr( state_nameprovbucketrHlast active_all most_active least_actives r _cmd_statusrDs!!!!!!    E  ""G YYx ' 'Fyy''Hii*++7xG 99[! $ $D V     #k # #$$$ %t % %&&& 2wx00 2 2333 w))++  *5**+++ / /D -t-- . . . . / ,7,,---ii*++G6G}}++--?< 474F44555  $ $ & &C8q==SBYY3"9YYY 6_ 6 6777 Gw;;== G G GHHH Iw==?? I I IJJJ  YW%<%<%>%>ITTE Y((** V220V Y Y  % % ' 'D  +,,, """qrr::H FKM   UU7H-- J++221555 55?? % MM!F) $ $ $uu\7++ 7?? 1 KK Y   Q M  Ds4yy D D' D D3@ D D DEEE533 j"-- 1:111CKK112222 @ >3v;;>>499V+<+<>>???  Xr"" L L qb F  0111  A155!34455D (QvY&((EE"2A66=((uu[!,,3((lA..5((55229 (( "& ((    h++J" YY    1"   KN../?@@EAJJ * + + +  quu%78899,6*,, !&6 : :A,,55a007,,EE,229,, !uu]A66= ,, &* ,, YY    1"    + , , ,!  quu%78899,6*,, !&6 : :A,,55a007,,EE,229,, !uu]A66= ,, &* ,, 1r*c ddlm}|stddSt t |dd}t t |dd}t t |ddp| }t t |d drd nd}|rtd ntd |#|std d"d}|||||}|di}|r|r(td|dddnktd|ddd|ddd|ddd|dd|std|r!|rtd ntd!dS)#Nrr6zAcurator: disabled via config; enable with `curator.enabled: true`r$dry_runF background synchronous consolidateTz7curator: running DRY-RUN (report only, no mutations)...zcurator: running review pass...ucurator: consolidation is off — running prune-only (deterministic stale/archive). Pass --consolidate or set `curator.consolidate: true` to enable the LLM merge pass.msgr r rc$t|dSN)r0)rs r _on_summaryz_cmd_run.._on_summarys c r*) on_summaryrrrauto_transitionszauto (preview): checkedu9 candidate skill(s) — no transitions applied in dry-runzauto: checked=z stale= marked_stalez archived=rJz reactivated= reactivateduFllm pass running in background — check `hermes curator status` laterzzdry-run: no changes applied. Read the report with `hermes curator status` and run `hermes curator run` (no flag) to apply.zdry-run: no changes applied. When the report lands, read it with `hermes curator status` and run `hermes curator run` (no flag) to apply.)rr r r) rOr7rlr0boolgetattrrrrun_curator_reviewr&) rxr7dryrrrrresultautos r_cmd_runrs      QRRRq wtY.. / /CgdL%8899Jwt]E::;;M:~Kwt]EBBCCM$$K 1 GHHHH /0007#:#:#<#<  H    ' ' (F ::(" - -D    8488Iq#9#9888     <)Q!7!7<<.!44<< HHZ33<< $xx q99<<    X VWWW    [     [    1r*cZddlm}|dtddS)Nrr6Tzcurator: pausedrOr7 set_pausedr0rxr7s r _cmd_pausers< t  1r*cZddlm}|dtddS)Nrr6Fzcurator: resumedrrs r _cmd_resumers< u  1r*cddlm}||jst d|jddS||jdt d|jddS) Nrr curator: 'u`' is bundled or hub-installed — cannot pin (only agent-created skills participate in curation)r$Tzcurator: pinned 'z ' (will bypass auto-transitions)r+r!is_agent_createdskillr0 set_pinnedrxr!s r_cmd_pinr"s!!!!!!  ' ' 3 3  B B B B   q4:t,,, Jdj J J JKKK 1r*cddlm}||jst d|jddS||jdt d|jddS) Nrr rue' is bundled or hub-installed — there's nothing to unpin (curator only tracks agent-created skills)r$Fzcurator: unpinned ''rrs r _cmd_unpinr/s!!!!!!  ' ' 3 3  R R R R   q4:u--- - - - -... 1r*c ddlm}|}|stddStdt |dt |dD]v}|drd nd }t|d }td |d dd|dddd|dd|d wtddS)zList curation-eligible skills that carry no provenance marker. The same population `status` summarizes, itemized. Useful before deciding what to hand over with `adopt`. rr u@curator: no unmanaged skills — every eligible skill is managedzunmanaged skills (z):c|dSNrM)xs rrZz%_cmd_list_unmanaged..Js & r*r[r#zcreated_by:nullz no markerrWrSrM44sz activity=r_4drd14sz (rRza adopt one with `hermes curator adopt `, or all with `hermes curator adopt --all-unmanaged`)r+r!r,r0r/rwr&r)rxr!rr(whyrs r_cmd_list_unmanagedr<sM "!!!!!  ' ' ) )D  PQQQq ,s4yy , , ,--- D11 2 2 2  #$55)=#>#>OKquu/0011  6 !  .22 9  ! )           ?@@@ 1r*cDddlm}tt|ddpg}t t|dd}|r:|rt ddS|}|st d dS|st d dSt t|d d}|r9t d t|d |D]}t d|dS|rt t|ddst dt|dt d td }n#ttf$rd}YnwxYw|dvrt ddSd}|D]3}| |\}} t d| |s|dz }4t|dkr2t dt||z dt||rdndS)uHand unmanaged skills to the curator by explicit user declaration. Provenance cannot be inferred from telemetry: a high patch count proves the agent MAINTAINS a skill, not that it AUTHORED it (the agent edits user-written skills on the user's behalf constantly). So adoption is never automatic — the user names what they're handing over, or passes ``--all-unmanaged`` to hand over every eligible skill at once. rr rN all_unmanagedFz=curator: pass either skill names or --all-unmanaged, not bothr$z%curator: no unmanaged skills to adoptz7curator: name a skill to adopt, or pass --all-unmanagedrzcurator: would adopt z skill(s) (dry run):z + yeszcurator: adopt z, unmanaged skill(s) into curator management?z9 they become eligible for automatic staleness + archivalz proceed? [y/N] rB>yrcurator: abortedr?zcurator: adopted /)r+r!listrrr0list_unmanaged_skill_namesr/inputstriplowerEOFErrorKeyboardInterrupt adopt_skill) rxr!names adopt_allrnreplyfailedokrs r _cmd_adoptrXs"!!!!! w--3 4 4EWT?E::;;I   Q R R R16688  9 : : :1  GHHHq74E2233G Fc%jjFFFGGG  A ***    q gdE599::  XE XXXYYY IJJJ -..4466<<>>EE+,   EEE   $ $ $ % % %1 F ))!,,C #     aKF 5zzA~~ D#e**v"5DDE DDEEE 11As=3E11FFcxddlm}||j\}}t d||rdndS)Nrr r?r$)r+r! restore_skillrr0rxr!rrs r _cmd_restorersR!!!!!!'' 33GB c  >11r*cddlm}||jdr"t d|jd|jddS||j\}}t d||rdndS) zManually archive an agent-created skill. Refuses if pinned. The auto-curator archives stale skills on its own schedule; this verb is for the user who wants to archive *now* without waiting for a run. rr rLru7' is pinned — unpin first with `hermes curator unpin `r$r?)r+r! get_recordrr&r0 archive_skillrs r _cmd_archivers "!!!!!dj))--h77  3 3 3%)Z 3 3 3   q'' 33GB c  >11r*recorddict Optional[int]c|dp|d}|sdS tjt|}n#tt f$rYdSwxYw|j |tj }tdtj tj |z j S)uDays since the skill's last activity (view / use / patch). Falls back to ``created_at`` so a skill that was authored but never used can still be pruned — otherwise never-touched skills would be immortal. Returns None only when both fields are missing or unparseable. rWrXNrr) r&rrr rrrrrrmaxrdays)rrrs r _idle_daysrs & ' ' C6::l+C+CB t  #CGG , , z "tt y ZZx|Z , , q8< --28 9 99s!AA'&A'c8ddlm}t|dd}|dkr!td|dtjd St t|d d }t t|d d }g}|D]l}|d r|d|j kr7t|}|||krO| |d|fm|std|ddS| dtdt|d|d|D]\}}td|dd|d|rtddS|s tdt|d} n'#t"t$f$rtdYdSwxYw| d vrtd!dSd} g} |D]<\}} ||\} }| r| dz } %| ||f=td"| d#t|| r.td$| D]\}}td|d%|dSdS)&aBulk-archive curator-managed skills idle for >= N days. Pinned skills are exempt. Already-archived skills are skipped. Default ``--days 90`` matches a conservative read of the curator's own archive threshold; adjust with ``--days``. Use ``--dry-run`` to preview. rr rZr$z"curator: --days must be >= 1 (got rR)filerFrrLrKNrMz6curator: nothing to prune (no unpinned skills idle >= zd)c|d S)Nr$r)cs rrZz_cmd_prune..s 1Q4%r*r[r?z skill(s) idle >= zd:rSr^z idle rDu (dry run — no changes made)z Archive z skill(s)? [y/N] z curator: aborted>rrrz curator: archived rz failures:z: )r+r!rr0sysstderrrrsr&STATE_ARCHIVEDrrusortr/rrrrrr)rxr!rr skip_confirm candidatesr(idlerMrrJfailures_rrs r _cmd_prunersG"!!!!! 4 $ $D axx :4:::LLLLq74E2233GeU3344LJ  ' ' ) )-- 55??   55>>[7 7 7 !}} <4$;; 1V9d+,,,,  OtOOOPPPqOOO((( Ac*oo A A A A ABBB ,, d *4***4***++++ /000q  Is:IIIJJPPRRXXZZEE+,    & ' ' '11   $ $ $ % % %1HH))a++D11C  ) MHH OOT3K ( ( ( ( = = =C OO = =>>> k! & &ID# $t$$s$$ % % % %q 1sAG G-,G-cddlm}|stddSt |ddpd}||}|td dStd |jdS) zuTake a manual snapshot of the skills tree. Same mechanism as the automatic pre-run snapshot, just user-initiated.rcurator_backupzacurator: backups are disabled via config (`curator.backup.enabled: false`); re-enable to snapshotr$reasonNmanual)ruEcurator: snapshot failed — check logs (backup disabled or IO error)z?curator: snapshot created at ~/.hermes/skills/.curator_backups/)rOrrlr0rsnapshot_skillsrM)rxrrsnaps r _cmd_backuprs%$$$$$  $ $ & &  G   q T8T * * 6hF  ) ) ) 8 8D | UVVVq WDI W WXXX 1r*cddlm}t|ddr#t|dSt|dd}||}||}|stdnWtd|rd t|znd d td t|d S||}td|j |rtd| ddtd| ddtd| dd| dpi}t|trf| dr(td| dddn)| dd}td|dtdt|ddsq td }n'#t t"f$rtd!Yd SwxYw|d"vrtd#d S||j $\} } } | rtd%| dStd&| d S)'a7Restore the skills tree from a snapshot. Defaults to newest. ``--list`` prints available snapshots and exits. ``--id `` picks a specific one. Without ``-y``, prompts for confirmation. A safety snapshot of the current tree is always taken first, so rollbacks are themselves undoable. rrrF backup_idNzhcurator: no snapshots exist yet. Take one with `hermes curator backup` or wait for the next curator run.zcurator: no snapshot matching zid z your query.z Available:r$zRollback target: z reason: r?z created_at: rXz skill files: skill_files cron_jobs backed_upz cron jobs: jobs_countz. (will be restored for skill-link fields only)z not capturedz cron jobs: not in snapshot (rRa This will replace the current ~/.hermes/skills/ tree (a safety snapshot of the current state is taken first so this is undoable). Cron jobs that still exist will have their skills/skill fields restored from the snapshot; all other cron fields are left alone.rzProceed? [y/N] z cancelled>rr cancelled)rr?ucurator: rollback failed — )rOrrr0summarize_backups_resolve_backup list_backupsrepr_read_manifestrMr& isinstancerrrrrrrollback) rxrr target_pathrmanifestcronransrrrs r _cmd_rollbackrs}%$$$$$tVU## n..00111qk400I 00;;K**,, 6 L     M.7I54 ??**\MMM    ,    .2244 5 5 5q,,[99H 0k. 0 0111 D = Xs ; ;==>>> A \3 ? ?AABBB B ]C @ @BBCCC||K((.B dD ! ! Dxx $$ DEdhh|Q&?&?EEE (N;;BBBBCCC  L 4 & & )**002288::CC+,    - 11  l " " +   1((;3C(DDJBQ  #   q /# / /000 1s63I** J Jcddlm}|}|stddS|D]}t|dS)z#List archived (recoverable) skills.rr zcurator: no archived skills)r+r!list_archived_skill_namesr0)rxr!rrMs r_cmd_list_archivedr\sb!!!!!!  1 1 3 3E  +,,,q d 1r*cddl}ddlm}|}t |ddrfd|D}t |dd}|dkr|d n7|d kr|d d n|dd t |ddr't ||dddS|st ddSdddd}|D]F}||ddddz||dd<Gt dt|d|dd|dd|dd t t dd d!dd"d#dd$d%dd&d%dd'd(dd)d%d* |D]}t|d+}t d|ddd,d!d|ddd#d|d-dd.d|d/dd.d|d0dd1d|d2dd.d|dS)3uShow usage telemetry for ALL skills, with provenance. Unlike `status` (curator-scoped to curated candidates), this lists every skill on disk — bundled built-ins and hub-installed included — so you can see how often each is actually used regardless of curation. rNr rNcFg|]}|dk|S)rNr%)r'r( prov_filters r z_cmd_usage..vs/FFFa155#6#6+#E#E#E#E#Er*ractivityrMc|dSrrrYs rrZz_cmd_usage..zs & r*r[recentc0|dpdS)NrWrBr%rYs rrZz_cmd_usage..}s&8 9 9 ?Rr*Trhc.|ddS)Nr_rr%rYs rrZz_cmd_usage..s&6 : :r*jsonFr)indent ensure_asciizcurator: no skills foundrOrPhubrOr$zskills: z total (agent=rQrPz hub=r$rRrSrr^origin8susez>4sviewpatchz>5sactz last_activityrW(raz>4drbrcz>5dr_) r r+r! usage_reportrrr0dumpsr&r/r) rx_jsonr!rsort_keycountsr(rrs @r _cmd_usager1hs!!!!!!  # # % %D$ d33KGFFFF4FFFtVZ00H6 )) **** X   ?? NNNN ::D IIItVU## ekk$quk==>>>q  ()))qQq 1 1F __/5zz!%% g:V:VXY/Z/Z]^/^quu\7++,,  W3t99 W W/ W W-3I-> W WFLUm W W W GGG  PW+ P PH+ P P O P PO P P&-O P P5:O P P P   quu/0011  63B3 '  uu\7++ 2  uu[!$$ ,  uu\1%% -  uu]A&& .    uu%q)) 1            1r*parentargparse.ArgumentParserct fdd}|dd}|t|dd }|d d d d |dddd|ddd|t |dd}|ddddd|dddd |d!d"dd#|d$d%dd&|t |d'd(}|t|d)d*}|t|d+d,}|d-d.|t|d/d0}|d-d.|t|d1d2t|d3d4} | d-d5d67| d8dd9| d!dd:| d;dd<| t|d=d>} | d-d.| t|d?d@t|dAdB} | d-d.| t|dCdD} | dEt dFdGH| dId;ddJ| d!d"ddK| t"|dLdM} | dNddOP| t$|dQdR}|dSddT|dUdVddWX|dId;ddY|t&dS)ZzAttach `curator` subcommands to *parent*. main.py calls this with the ArgumentParser returned by ``subparsers.add_parser("curator", ...)``. c<dfdS)Nrr$) print_help)ar2s rrZzregister_cli..s(9(9(;(;Q'?'Br*)funccurator_command)deststatusz#Show curator status and skill stats)helpusagezJShow usage telemetry for ALL skills (built-in, hub, agent) with provenancez--sort)rrrMrzlSort order: activity (most-used first, default), recent (most-recently-active first), or name (alphabetical))choicesdefaultr<z --provenancer#NzOnly show skills of this originz--json store_truez/Emit the full report as JSON instead of a table)actionr<runzTrigger a curator review nowz--syncz --synchronousrz@Wait for the LLM review pass to finish (default for manual runs))r:rAr<z --backgroundrzGStart the LLM review pass in a background thread and return immediatelyz --dry-runrukReport only — no state changes, no archives, no consolidation (use this to preview what curator would do)z --consolidaterzForce the LLM umbrella-building consolidation pass on for this run, overriding the config default (off). Without this flag the run is prune-only unless `curator.consolidate: true` is set.pausezPause the curator until resumedresumezResume a paused curatorpinz4Pin a skill so the curator never auto-transitions itrz Skill nameunpinz Unpin a skillzlist-unmanagedz7List curation-eligible skills with no provenance markeradoptzGHand unmanaged skills to the curator (provenance is a user declaration)*z8Skill name(s) to adopt. Omit when using --all-unmanaged.)nargsr<z--all-unmanagedzAAdopt every curation-eligible skill that has no provenance markerz3List what would be adopted without writing anythingz--yesz0Skip the confirmation prompt for --all-unmanagedrestorezRestore an archived skillz list-archivedzList archived skillsarchivezBManually archive a skill (move to .archive/, excluded from prompt)prunezCBulk-archive curator-managed skills idle for >= N days (default 90)z--daysrz5Archive skills idle for at least N days (default: 90))typer?r<z-yzSkip the confirmation promptz,Show what would be archived without doing itbackupzoTake a manual tar.gz snapshot of ~/.hermes/skills/ (curator also does this automatically before every real run)z--reasonz;Free-text label stored in manifest.json (default: 'manual'))r?r<rzJRestore ~/.hermes/skills/ from a curator snapshot (defaults to the newest)z--listz3List available snapshots and exit without restoringz--idrz6Snapshot id to restore (see `--list`); default: newest)r:r?r<zSkip confirmation prompt) set_defaultsadd_subparsers add_parserr add_argumentr1rrrrrrrrrrrrrr)r2subsp_statusp_usagep_runp_pausep_resumep_pinp_unpinp_adopt p_restore p_archivep_prunep_backup p_rollbacks` r register_clirash  BBBBCCC  &7 8 8Dx.STTH {+++oo YG 8*D   ;T .  > j))) OOE(FO G GE / l O \, V )L;  mLL  H%%%oog,MoNNG j)))x.GHHH {+++ OOE(^O _ _E w\222 H%%%oogOo<Standalone entry (also usable by hermes_cli.main fallthrough).zhermes curator)progr8Nr)argparseArgumentParserra parse_argsrr6r)argvparserrxfns rcli_mainrjEs~  $*: ; ; ;F   T " "D vt $ $B zq rr$xx}1  r*__main__)rr r r )r r)r r)rrr r)r2r3r rr)!__doc__ __future__rrdrrrpathlibrtypingrrr4rrrrrrrrrrrrrrrr1rarj__name__exitrr*rrrsP#""""" ''''''''####(:N N N N b< < < < ~                      85555p$::::&A A A A H    &F F F F R     9 9 9 9 @Z0Z0Z0Z0z      z CHXXZZr*