yj":pUdZddlmZddlZddlZddlZddlmZddlm Z m Z m Z m Z m Z ddlZddlmZejeZejdZejdZiad ed <dad ed <d7dZd8dZd9dZd:dZd;dZdd!Z"d?d#Z# d@dAd+Z$dBd,Z% dCdDd4Z&dBd5Z'dEd6Z(dS)FuSkill bundles — aliases that load multiple skills under one slash command. A skill bundle is a small YAML file that names a set of skills to load together. Invoking ``/`` from the CLI or gateway loads every referenced skill's full content into a single user message, the same way ``/`` does — but for N skills at once. Storage ------- Bundles live in ``~/.hermes/skill-bundles/*.yaml`` (and the equivalent profile-aware directory under ``HERMES_HOME``). Each file looks like:: name: backend-dev description: Backend feature work — code review, testing, PR workflow. skills: - github-code-review - test-driven-development - github-pr-workflow instruction: | Optional extra guidance to inject above the skill bodies. The file's stem is treated as a fallback name when ``name:`` is absent, so dropping a YAML into the directory is enough to register a new bundle. Conflict resolution ------------------- If a bundle and a skill share the same slash name, the bundle wins. The slash command dispatch checks bundles first, then falls back to skills. This is the intended behavior — a user who names a bundle ``research`` explicitly wants ``/research`` to mean their bundle, not whatever skill happens to share the slug. Public API ---------- - :func:`get_skill_bundles` — return ``{"/slug": bundle_info}`` - :func:`resolve_bundle_command_key` — map a user-typed command to its slug - :func:`build_bundle_invocation_message` — produce the full user message - :func:`reload_bundles` — re-scan disk and return a diff - :func:`list_bundles` — return rich info for display (``hermes bundles``) - :func:`save_bundle` / :func:`delete_bundle` — file-level operations ) annotationsN)Path)AnyDictListOptionalTuple)get_hermes_homez [^a-z0-9-]z-{2,}Dict[str, Dict[str, Any]]_bundles_cachezOptional[float]_bundles_cache_mtimereturnrctjd}|r!t|St dz S)zReturn the canonical bundles directory under HERMES_HOME. Honors ``HERMES_BUNDLES_DIR`` for tests; falls back to ``/skill-bundles``. HERMES_BUNDLES_DIRz skill-bundles)osenvirongetr expanduserr )overrides 9/home/ragecks/.hermes/hermes-agent/agent/skill_bundles.py _bundles_dirrBsI z~~233H+H~~((***    ..namestrc|dddd}td|}td|d}|S)N -_)lowerreplace_BUNDLE_INVALID_CHARSsub_BUNDLE_MULTI_HYPHENstrip)rcmds r_slugifyr'Nsl **,,  sC ( ( 0 0c : :C  # #B , ,C  " "3 , , 2 23 7 7C Jr List[Path]ct}|sgSg}dD]7}|t||8|S)N)z*.yamlz*.yml)rexistsextendsortedglob)basefilesexts r_iter_bundle_filesr1Us` >>D ;;== E"-- VDIIcNN++,,,, Lrr/floatcpt}g}|r> ||jn#t $rYnwxYw|D]?} ||j0#t $rY>D F {{}}  MM$))++. / / / /    D    MM!&&((+ , , , ,    H  )3v;;;c)s#,A A A (,B B"!B"pathOptional[Dict[str, Any]]c |d}n4#t$r'}td||Yd}~dSd}~wwxYw t j|}n9#tj$r'}td||Yd}~dSd}~wwxYwt|tstd|dSt| dp|j  }|std|dS| d pg}t|tr|std |dSd |D}|std |dSt| d pd }t| dpd }t|}|std|dS|||pdt|d||t|dS)uParse a single bundle YAML file. Returns ``None`` on any error. Errors are logged at WARNING level. We don't raise — a broken bundle shouldn't take down slash command discovery. utf-8encodingzCould not read bundle %s: %sNzInvalid YAML in bundle %s: %sz$Bundle %s is not a mapping; skippingrzBundle %s has no name; skippingskillsz&Bundle %s has no skills list; skippingcg|]D}t|#t|ESrr%.0ss r z%_load_bundle_file..s9 ? ? ?A  ?c!ffllnn ? ? ?rz)Bundle %s has empty skills list; skipping descriptionr instructionz&Bundle %s yielded empty slug; skippingzLoad z skills as a bundle)rslugrJrBrKr<) read_textr7loggerwarningyaml safe_load YAMLError isinstancedictrrstemr%listr'len) r<rawexcdatarrBrJrKrLs r_load_bundle_filer[tsu nngn.. 5tSAAAttttt~c"" >6cBBBttttt dD ! !=tDDDt txx,49 - - 3 3 5 5D 8$???t XXh   %2F fd # #6?FFFt ? ?f ? ? ?F BDIIItdhh}--344::<>D ?FFFt"N&Nc&kk&N&N&N"D   s, A AA A##B2BBct}i}|D]R}t|}|sd|d}||vr*td||||dM|||<S|at |a|S)uScan the bundles directory and rebuild the cache. Returns the same mapping as :func:`get_skill_bundles` — ``"/slug"`` → bundle info dict. Later bundles with a duplicate slug are skipped with a warning (first wins, alphabetical order). /rLz,Duplicate bundle slug %s from %s; keeping %sr<)r1r[rNrOr r;r )r/outr:infokeys r scan_bundlesras  E%'C    ##   $v,   #:: NN>QC(    CN%e,, Jrct}t|}tr t|krt tS)zReturn the current bundle mapping, rescanning when disk changed. Cheap to call repeatedly: only rescans when the bundles directory or any bundle file's mtime is newer than the cached snapshot. )r1r;r r ra)r/ current_mtimes rget_skill_bundlesrds>  Eu%%M 1]BB rcommand Optional[str]cd|sdSd|dd}|tvr|ndS)zResolve a user-typed command to its canonical bundle slash key. Hyphens and underscores are treated interchangeably to mirror the skill-command behavior (Telegram converts hyphens to underscores in bot command names). Nr]rr)r!rd)recmd_keys rresolve_bundle_command_keyrisG t-'//#s++--G!2!4!44477$>rDict[str, Any]cd d}|tt}||tttz }tttz }tttz}fd|Dfd|D|t dS) zRe-scan the bundles directory and return a diff. Mirrors :func:`agent.skill_commands.reload_skills` so callers can use the same display logic. Returns a dict with ``added``, ``removed``, ``unchanged``, and ``total`` keys. cmdsr rDict[str, str]c>d|DS)Ncli|]1\}}|d|pidd2S)r]rJr)lstripr)rGkvs r z5reload_bundles.._snapshot..s:YYYDAq R}}]B??YYYr)items)rls r _snapshotz!reload_bundles.._snapshotsYYDJJLLYYYYrc&g|] }||dS)rrJrD)rGnafters rrIz"reload_bundles..s%LLL11U1X66LLLrc&g|] }||dSrwrD)rGrxbefores rrIz"reload_bundles..s%QQQaQvay99QQQr)addedremoved unchangedtotal)rlr rrm)r rar,setrW)runew added_names removed_namesr~ryr{s @@rreload_bundlesrsZZZZY~ & &F ..C IcNNEUc&kk122K3v;;U344Ms5zzCKK/00IMLLL LLLQQQQ=QQQU   rList[Dict[str, Any]]cft}t|dS)z6Return a sorted list of bundle info dicts for display.c|dS)NrLrD)bs rzlist_bundles..s !F)r)r`)rdr,values)bundless r list_bundlesrs.!!G '..""(;(; < < <>>>>>118DDD !LGH LUUDv,K (^F//52#(#(n"++--  Z4//  $$ZAAA  NN: & & & .4+ i  ' ':+G+G OOJ4* 5 5 5   2 2 2 2 2 2 HZ 1 1 1 1 1    D  E{ D D D   "        J'''' t  - - -|$$ - - -  ;  3$))L1133 LOM79K9KMMNNN  QDIIh>D NLLLLMMM >>tNNN **rFrB List[str]rJrK overwriteboolc|pd}|stdd|D}|stdt|}|r|st d||jdd||d}|r||d <|r||d <|tj |d d d t|S)zWrite a bundle to disk and invalidate the cache. Raises ``FileExistsError`` if the target exists and ``overwrite`` is False. Raises ``ValueError`` if the inputs are unusable. rzBundle name is requiredcg|]D}t|#t|ESrDrErFs rrIzsave_bundle..s9GGGA Gc!ffllnnGGGrz(Bundle must reference at least one skillzBundle already exists at T)parentsexist_ok)rrBrJrKF) sort_keys allow_unicoder?r@) r%rrr*FileExistsErrorparentmkdir write_textrP safe_dumpra)rrBrJrKrcleaned_skillsr<payloads r save_bundlers& JB    D 42333GGfGGGN ECDDD 4 D {{}}BYB@$@@AAAKdT222'+~FFG-!, -!, OO w%tDDDNNN Krct|}|std||t |S)zvDelete a bundle by name. Returns the deleted path. Raises ``FileNotFoundError`` if the bundle doesn't exist. z No bundle at )rr*FileNotFoundErrorunlinkra)rr<s r delete_bundlersS 4 D ;;==8 6 6 6777KKMMMNNN Krcht|}td|S)z+Look up a bundle by name (slug-normalized).r])r'rdrrs r get_bundlers- D>>D    " ":t:: . ..r)rr)rrrr)rr()r/r(rr2)r<rrr=)rr )rerrrf)rrj)rr)rNN) rhrrrrrrrrr)rrrr)rrF) rrrBrrJrrKrrrrr)rrrr=))__doc__ __future__rloggingrrepathlibrtypingrrrrr rPhermes_constantsr getLogger__name__rNcompiler"r$r __annotations__r rr'r1r;r[rardrirrrrrrrrDrrrsY(((T#""""" 33333333333333 ,,,,,,  8 $ $# =11!rz(++,.....(,,,,, / / / /*****1111h6     ? ? ? ?4==== sIsIsIsIsIv++++ #####L    //////r