`gj:UdZddlmZddlZddlZddlZddlmZddlm Z m Z m Z m Z m Z ddlZddlmZej"eZej(dZej(dZiad ed <dad ed <dd ZddZddZddZd dZd!dZd!dZ d"dZ!d#dZ"d$dZ# d% d&dZ$d'dZ% d( d)dZ&d'dZ'd*dZ(y)+uSkill 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_mtimectjjd}|rt|j 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 F/root/.hermes/venv/lib/python3.12/site-packages/agent/skill_bundles.py _bundles_dirrBs; zz~~23HH~((**   ..c|jjddjdd}tjd|}tjd|j d}|S)N -_)lowerreplace_BUNDLE_INVALID_CHARSsub_BUNDLE_MULTI_HYPHENstrip)namecmds r_slugifyr%Ns[ **,  sC ( 0 0c :C  # #B ,C  " "3 , 2 23 7C Jrct}|jsgSg}dD]+}|jt|j |-|S)N)z*.yamlz*.yml)rexistsextendsortedglob)basefilesexts r_iter_bundle_filesr.UsI >D ;;= E"- VDIIcN+,- LrcJt}g}|jr* |j|jj|D],} |j|jj.|r t |SdS#t $rYKwxYw#t $rYXwxYw)zHighest mtime across the bundle files plus the dir itself. Watching the directory mtime catches deletions; watching individual files catches edits. Together they're a cheap freshness check. g)rr'appendstatst_mtimeOSErrormax)r,r+mtimesfs r _max_mtimer7_s >D F {{}  MM$))+.. /  MM!&&(++ , !3v;)c)       s#)B )B BB B"!B"c~ |jd} t j |}t|tstjd|yt|jdxs |jj}|stjd|y|jd xsg}t|tr|stjd |y|Dcgc]5}t|jst|j7}}|stjd |yt|jd xsd j}t|jdxsd j}t|} | stjd|y|| |xsdt|d||t|dS#t$r!}tjd||Yd}~yd}~wwxYw#tj $r!}tjd||Yd}~yd}~wwxYwcc}w)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; skippingr#zBundle %s has no name; skippingskillsz&Bundle %s has no skills list; skippingz)Bundle %s has empty skills list; skipping descriptionr instructionz&Bundle %s yielded empty slug; skippingzLoad z skills as a bundle)r#slugr=r<r>path) read_textr3loggerwarningyaml safe_load YAMLError isinstancedictstrrstemr"listr%len) r@rawexcdatar#r<sr=r>r?s r_load_bundle_filerQts nngn.~~c" dD !=tD txx,499 - 3 3 5D 8$? XXh  %2F fd #6?F&, ?A c!flln ?F ? BDIdhh}-34::D ?F"Nc&k]:M&N"D  E 5tSA >>6cB @s:GH"H:H: HG;;HH7H22H7ct}i}|D]@}t|}|sd|d}||vrtjd||||d<|||<B|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). /r?z,Duplicate bundle slug %s from %s; keeping %sr@)r.rQrBrCr r7r )r,outr6infokeys r scan_bundlesrWs  E%'C   # $v,  #: NN>QC(  C N%e, Jrcjt}t|}tr t|k7r t 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. )r.r7r r rW)r, current_mtimes rget_skill_bundlesrZs,  Eu%M 1]B rcR|syd|jdd}|tvr|SdS)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). NrSrr)rrZ)commandcmd_keys rresolve_bundle_command_keyr^s8 '//#s+,-G!2!447>$>rcdd}|t}t}||}tt|t|z }tt|t|z }tt|t|z}|Dcgc] }|||d c}|Dcgc] }|||d c}|t |dScc}wcc}w)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. c |jDcic]+\}}|jd|xsijdd-c}}Scc}}w)NrSr=r)itemslstripr)cmdskvs r _snapshotz!reload_bundles.._snapshots<LPJJLYDAq R}}]B??YYYs0A)r#r=)addedremoved unchangedtotal)rcr returnzDict[str, str])r rWr)setrL)rfbeforenewafter added_names removed_namesrins rreload_bundlesrssZ~ &F .C cNEUc&k12K3v;U34Ms5zCK/0IALL11U1X6LCPQaQvay9QU  LQs B;CcNt}t|jdS)z6Return a sorted list of bundle info dicts for display.c |dS)Nr?)bs rzlist_bundles..s !F)r)rV)rZr)values)bundless r list_bundlesr{s!G '.."(; <r)task_id)bump_usez[Loaded as part of the "z" skill bundle.]) session_idz&[IMPORTANT: The user has invoked the "z" skill bundle, loading zL skills together. Treat every skill below as active guidance for this turn.]zBundle: zSkills loaded: z, zSkills missing (skipped): z-Skills disabled for this platform (skipped): zBundle instruction: zUser instruction:  z )rZragent.skill_commandsr}r~agent.skill_utilsr Exceptionrlr"addr0tools.skill_usagerrLjoinr()r]user_instructionrrrzrUr}r~rdisabled_names loaded_namesmissingdisabled skill_blocksseen bundle_namer<extra_instructionskill_id identifierloaded loaded_skill skill_dir skill_nameractivation_note header_linesheaders rbuild_bundle_invocation_messagers4 !G ;;w D O>18D!LGH LUDv,K (^F/52#(n"++- Z4/  $ZA NN: & .4+ i  ':+G OOJ4* 5   2 Z '{m3C D   "    J'G#(J  1 >|$%&- - ;- $))L123 L879K8LMN;DIIhD <x/KLMM >tfEN **rc|xsdj}|s td|Dcgc]5}t|jst|j7}}|s tdt|}|j r|st d||j jdd||d}|r||d<|r||d <|jtj|d d d t|Scc}w)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 requiredz(Bundle must reference at least one skillzBundle already exists at T)parentsexist_ok)r#r<r=r>F) sort_keys allow_unicoder9r:) r"rrIrr'FileExistsErrorparentmkdir write_textrD safe_dumprW) r#r<r=r> overwriterPcleaned_skillsr@payloads r save_bundlers JB   D 233.4GA c!fllnGNG CDD 4 D {{}Y 9$@AAKKdT2'+~FG!, !, OO w%tDN K)Hs C?C?ct|}|jstd||jt |S)zvDelete a bundle by name. Returns the deleted path. Raises ``FileNotFoundError`` if the bundle doesn't exist. z No bundle at )rr'FileNotFoundErrorunlinkrW)r#r@s r delete_bundlers< 4 D ;;=-v 677KKMN KrcPt|}tjd|S)z+Look up a bundle by name (slug-normalized).rS)r%rZrrs r get_bundlers% D>D   " "Qtf: ..r)rkr)r#rIrkrI)rk List[Path])r,rrkfloat)r@rrkOptional[Dict[str, Any]])rkr )r\rIrkz Optional[str])rkzDict[str, Any])rkzList[Dict[str, Any]])rNN) r]rIrrIr str | Nonerrrkz*Optional[Tuple[str, List[str], List[str]]])r#rIrkr)rrF) r#rIr<z List[str]r=rIr>rIrboolrkr)r#rIrkr))__doc__ __future__rloggingrrepathlibrtypingrrrrr rDhermes_constantsr getLogger__name__rBcompilerr!r __annotations__r rr%r.r7rQrWrZr^rsr{rrrrrrvrrrsJ(T# 33 ,   8 $# =1!rzz(+,.).(,o, /**1h6  ?4= sI sIsIsI sI 0 sIv+ # # ## #  #  #L /r