sj\? , UdZddlmZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlZddlZddlZddlZddlmZddlmZmZddlmZddlmZddlmZmZmZmZm Z m!Z!m"Z"m#Z#m$Z$m%Z%m&Z&dd l'm(Z(m)Z)m*Z*m+Z+dd l,m-Z-dd l.m/Z/m0Z0dd l1m2Z2m3Z3dd l4m5Z5m6Z6ddl7m8Z8m9Z9m:Z:ddl7m;Z<ddl=m>Z>m?Z?m@Z@ddZA ddlBZBn #eC$rdZBYnwxYwGddeDZEe jFeGZHe jIddJKdvaLdaMdddZNeNhdZOdePd <d!hZQdePd"<d#ZRd$ZSdd*ZTdd,ZUdd.ZVeWd/hZXd0ZYd0ZZd1Z[d2Z\ej]d3Z^d4Z_d5Z`d6Zadd7Zbdd:Zcdd<Zdd=Zed>Zfd?ZgehZid@ZjejkZliZmdAePdB<dCZneddEZoddGZpddIZqddKZrhdLZsdePdM<ddOZtddQZuhdRZvdePdS<dTZwexfexfeyfeyfeyezfeyezfe{fe{fe|fe|fe}fe}fdU Z~dVePdW<dd[Zdd`ZddcZd dfZd!d"dkZd#dmZd!d$dnZeGdodpZedqrGdsdtZedqrGdudvZedqrGdwdxZedqrGdydzZeGd{d|ZeGd}d~Zej]dZeWhdZej]dZdZiZdePd<ejZd%dZd&dZd'dZd(dZd)dZed*dZGddZGddZGddZdadePd<iZdePd<ejkZddZd+dZd,dZd-dZd.dZdddZdadePd<ejZd-dZd/d0dZdZd-dZd1dZd2dZd2dZ d3d4dZd,dZd5dZd6dZd7dZd8dZd9d„Zd:dĄZdddŜd;d̄ZejZedqrGd̈́dΦZ d<d=dӄZd-dԄZ d>d?d߄Z d>d@dZ d>dAdZ d>dAdZdddddBdZ d>dCdZdddddddddDdZdddddddddddd dEdZĐddFdZŐdZƐdGdZdZȐdHdZɐdIdZʐdJd ZːdKd Z̐dLd ZdS(Mu Hermes Plugin System ==================== Discovers, loads, and manages plugins from four sources: 1. **Bundled plugins** – ``/plugins//`` (shipped with hermes-agent; ``memory/`` and ``context_engine/`` subdirs are excluded — they have their own discovery paths) 2. **User plugins** – ``~/.hermes/plugins//`` 3. **Project plugins** – ``./.hermes/plugins//`` (opt-in via ``HERMES_ENABLE_PROJECT_PLUGINS``) 4. **Pip plugins** – packages that expose the ``hermes_agent.plugins`` entry-point group. Later sources override earlier ones on name collision, so a user or project plugin with the same name as a bundled plugin replaces it. Each directory plugin must contain a ``plugin.yaml`` manifest **and** an ``__init__.py`` with a ``register(ctx)`` function. Lifecycle hooks --------------- Plugins may register callbacks for any of the hooks in ``VALID_HOOKS``. The agent core calls ``invoke_hook(name, **kwargs)`` at the appropriate points. Tool registration ----------------- ``PluginContext.register_tool()`` delegates to ``tools.registry.register()`` so plugin-defined tools appear alongside the built-in tools. ) annotationsN)contextmanager) dataclassfieldwraps)Path) AnyCallableDictIterableListMappingOptionalSetTupleTypeUnion)get_hermes_homehermes_home_keyreset_hermes_home_overrideset_hermes_home_override)replacement_coordinator)env_var_enabledfast_safe_load)cfg_getload_config_readonly)OBSERVER_SCHEMA_VERSIONVALID_MIDDLEWARE)CAPABILITY_REGISTRYVALID_CAPABILITY_IDSplugin_capability_granted)parse_declared_capabilities)LEGACY_RELAY_PLUGIN_KEYSRELAY_PLUGINS_CONFIG_ENVlegacy_relay_plugin_keysreturnr ctjd}|rt|Sttjjdz S)zLocate the bundled ``plugins/`` directory. Honours ``HERMES_BUNDLED_PLUGINS`` (set by the Nix wrapper / packaged installs) so read-only store paths are consulted first. Falls back to the in-repo path used during development. HERMES_BUNDLED_PLUGINSplugins)osgetenvr __file__resolveparent) env_overrides 6/home/agent/.hermes/hermes-agent/hermes_cli/plugins.pyget_bundled_plugins_dirr2QsM9566L"L!!! >> ! ! # # * 1I ==ceZdZdZdS)PluginToolOverrideErrorzRaised when a plugin attempts to override a built-in tool without operator opt-in via ``plugins.entries..allow_tool_override``. N)__name__ __module__ __qualname____doc__r3r1r5r5csr3r5HERMES_PLUGINS_DEBUG>1onyestrueFforceboolNonec4|r;tjdddvatrt rdSt jtj }| t j | t j dt|t t j dt_datddS)zWhen HERMES_PLUGINS_DEBUG is on, tee plugin logs to stderr at DEBUG. Idempotent: only attaches the handler once per process unless ``force`` is passed. Does not touch the root logger or other Hermes loggers. r;r<>r=r>r?r@Nz#[plugins] %(levelname)s %(message)sTuCHERMES_PLUGINS_DEBUG=1 — verbose plugin discovery logging enabled)r+r,striplower_PLUGINS_DEBUG_DEBUG_HANDLER_INSTALLEDlogging StreamHandlersysstderrsetLevelDEBUG setFormatter Formatterlogger addHandler propagatedebug)rAhandlers r1_install_plugin_debug_handlerrVs  #92>>DDFFLLNNS   5#CJ//G W]### *+PQQRRR g OOGM"""F# LLMr3>% pre_verify pre_command pre_llm_call on_stream_end post_llm_call pre_tool_call subagent_stopon_session_endpost_tool_callsubagent_starton_stream_deltaon_stream_startpre_api_requeston_session_reseton_session_startpost_api_requestapi_request_errorpre_transcriptionon_interim_messageon_skill_lifecyclekanban_task_blockedkanban_task_claimedon_session_finalizepre_approval_requestpre_gateway_dispatchtransform_llm_outputkanban_task_completedtransform_tool_resultgateway_platform_eventon_kanban_task_updatedpost_approval_responseon_kanban_dispatch_tickon_kanban_worker_exitedon_kanban_worker_spawnedtransform_terminal_outputon_kanban_worker_stale_claim"transform_api_error_classificationzSet[str] VALID_HOOKSr{SHELL_UNSUPPORTED_HOOKSzhermes_agent.pluginsz hermes_agent.plugin_capabilities entry_pointsr groupstrlistct|dr#t|St|tr#t|gSfd|DS)zCReturn one metadata entry-point group across supported Python APIs.selectrc*g|]}|jk |Sr:r).0eprs r1 z-_select_entry_point_group..s% ; ; ;2U):):B):):):r3)hasattrrr isinstancedictget)r~rs `r1_select_entry_point_grouprs~|X&&6L''e'44555,%%1L$$UB//000 ; ; ; ; ; ; ;;r3List['PluginManifest']c  g} tj}t|t}t|t }n4#t $r'}td||cYd}~Sd}~wwxYw|D]] g}tD]?} j d| t fd|Dr| |@t dd}t|dd}t j tt|ddpd|%t|d dpdndd j j t%| j  } t' j| _| | #t $r6}td t d d|Yd}~Wd}~wwxYw|S)uReturn metadata-only manifests for installed entry-point plugins. Composes the full entry-point manifest contract in one place: * **Kind classification** — the module source is resolved import-free (``_resolve_module_source``) and scanned for provider markers (``_detect_kind_from_source``), so memory providers (``exclusive``) and model providers (``model-provider``) are routed to their own discovery systems instead of being eagerly imported here. * **Capability declarations** — read from the companion ``hermes_agent.plugin_capabilities`` entry-point group (declarations named ``.`` pointing at the same object), so consent/introspection is accurate without importing plugin code. Failures are isolated per entry point: one malformed distribution must not blank the manifests of every other installed plugin. zEntry-point scan failed: %sN.c3NK|]}|jko|jjkV dSN)namevalue)r declarationdeclaration_namers r1 z0discover_entrypoint_manifests..sT$ $(886#)RX5r3distmetadataversionr<Summary entrypoint)rr descriptionsourcepathkey capabilitiesz'Entry-point manifest for %r skipped: %sr?) importlibrr~rENTRY_POINTS_GROUPENTRY_POINT_CAPABILITIES_GROUP ExceptionrQrTr!ranyappendgetattrPluginManifestrrr_parse_declared_capabilities_classify_entrypoint_value_kindkind) manifestseps group_epscapability_epsexcr capabilityrrmanifestrrs @@r1discover_entrypoint_manifestsrsg$')I --//-c3EFF 2 /    2C888##" L2 4 4 &(g#<#< #<#< (64 !'' 3332vt,,DtZ66H%WGD)R88>B?? + Y339r:::#XG9 "'Hz#czt|to&tt|S)zDReturn whether *value* is a stable, heading-safe section identifier.)rrrB_SYSTEM_PROMPT_SECTION_ID_RE fullmatchrs r1!is_valid_system_prompt_section_idrs/ eS ! ! Yd+G+Q+QRW+X+X&Y&YYr3 section_idcontentc>t|dt|d|S)zJRender an auditable, length-framed block recoverable from the full prompt.z" )%_SYSTEM_PROMPT_SECTION_HEADING_PREFIXlen)rrs r1format_system_prompt_sectionrs= 1 *  ,/LL     r3sectionscx|sdSd|D}tdd|zdtzS)z=Render the canonical container used for persistence recovery.r<cBg|]}t|j|jSr:)ridrritems r1rz1format_system_prompt_sections..s' W W Wd*47DLAA W W Wr3 z )PLUGIN_SECTIONS_STARTjoinPLUGIN_SECTIONS_END)rblockss r1format_system_prompt_sectionsr sQ r W Wh W W WF# ' ' '&++f*=*= =@ZEX@Z@Z ZZr3hermes@hermes_pluginszDict[str, str]_BARE_MODULE_SCOPEc<tfd}|S)uDMake snapshot → write → lease attachment one atomic transaction.cntj5|i|cdddS#1swxYwYdSr)r transaction)argskwargsmethods r1wrappedz(_serialized_replacement..wrapped(s $ 0 2 2 + +64*6** + + + + + + + + + + + + + + + + + +s *..r)rrs` r1_serialized_replacementr&s3 6]]++++]+ Nr3homec#xKt|} dVt|dS#t|wxYw)zBBind discovery and loading to the manager's immutable Hermes home.N)rr)rtokens r1_plugin_home_scoper0sL %T * *E* "5)))))"5))))s(9rc t|S)zbackendplatform exclusivermodel-provider_VALID_PLUGIN_KINDSrc$dd|D}|dpd}tj|ddd}d|d |S) zGReturn a readable, collision-resistant namespace for a portable plugin.r<c3vK|]4}|r|s|dvr|ndV5dS)z_--N)isasciiisalnum)rchs r1rz,_portable_skill_namespace..ws\ jjllD Dd r3z-_pluginutf-8Nr agent-plugin-r)rrFrEhashlibsha256encode hexdigest)rslugdigests r1_portable_skill_namespacerts 77))++  D ::d   'xD ^CJJw// 0 0 : : < .sU  yy e        r3)remailurlNr<)rrrrrs`r1_display_authorrsg%!! yy    1      22CJJ.r3>rrtagsemitshookslabelauthorrdependslicenselistensrhomepage platforms api_versionrr optional_env requires_env config_schemaprovides_hooksprovides_toolsmanifest_versionpip_dependenciesrequires_pluginspython_dependenciesexternal_dependenciesprovides_web_providersprovides_browser_providers_KNOWN_MANIFEST_FIELDS) rstringintintegerfloatnumberrBbooleanrarrayrrzDict[str, tuple]_CONFIG_SCHEMA_TYPESdatarDict[str, Any]c  i}|dd} t|}n5#ttf$r!td||d}YnwxYw|t kr"td||t ||d<|d}|d|d<nL t||d<n8#ttf$r$td||d|d<YnwxYwg}|d}|2t|tstd |d}|pgD]}t|tr| |dd 0t|trut|d trM|d rE|d } | |d | t| ndd td ||||d<g} |d} | 2t| tstd|d} | pgD]o}t|tr<| r(| | Std||p| |d<|d} i} | 2t| tstd|d} | pi D]\}}t|tstd||7|d}|kt|tvrCtd|||dt#tt%|| t|<| |d<t|dpd|d<t|dpd|d<|d}|2t|tstd|d}d|pgD|d<t#t'|t*z }|r>|dkr tjn tj}|d|d||S)uValidate and normalize the manifest v2 fields (#64165). Returns kwargs for :class:`PluginManifest`. Every problem is a warning, never a load failure — v2 metadata is advisory and additive. r&rz?Plugin %s: manifest_version %r is not an integer; treating as 1zrPlugin %s: manifest_version %d is newer than this Hermes supports (%d); loading anyway and ignoring unknown fieldsr Nz5Plugin %s: api_version %r is not an integer; ignoringr(z4Plugin %s: requires_plugins must be a list; ignoring)r version_rangerr:zjPlugin %s: requires_plugins entry %r must be a plugin id string or a {id, version_range} mapping; skippingr)zNPlugin %s: python_dependencies must be a list of requirement strings; ignoringzXPlugin %s: python_dependencies entry %r must be a non-empty requirement string; skippingr#z4Plugin %s: config_schema must be a mapping; ignoringzPPlugin %s: config_schema entry %r must be a mapping (e.g. {type: str}); skippingtypezgPlugin %s: config_schema key %r declares unknown type %r (known: %s); type check will be skipped for itrrr<rrz(Plugin %s: tags must be a list; ignoringc,g|]}t|Sr:r)rts r1rz-_parse_manifest_v2_fields..#s444a3q66444r3r.zdPlugin %s: unknown manifest field(s) ignored: %s (newer manifest schema or typo; plugin still loads))rr0 TypeError ValueErrorrQwarningSUPPORTED_MANIFEST_VERSIONrrrrrrEitemsrFr6rsortedrrkeysr-rT)r7routraw_mvmvraw_apidepsraw_depsrvrpydeps raw_pydeps raw_schemaschemaskeyspecstyperaw_tagsunknownlogs r1_parse_manifest_v2_fieldsrWs CXX(! , ,F [[ z " M       &&& H /   !Chh}%%G!M &!$WC  :& & & & NNGg   "&C     &"$Dxx*++HJx$>$> BC   B   dC  KKtd;; < < < < g & & :dhhtnnc+J+J tTXz /**B KK4j,.NR     NNDEH$    #CF/00JjT&B&B !$     b dC  TZZ\\  MM$**,, ' ' ' ' NN/03T    "(C/**JFjW&E&E BC    !'R..00'' d$((  NN/03T        U!1!1!3!3;O!O!O NNAT5$))F3G,H,H"I"I    !JJs4yy!C),,233C N$((:..4"55C OxxHJx$>$>A3GGG44HN444CKS%%(>>??G "afnnV\  B 7##   Js!*/AA/C2C76C7 plugin_idrPsettings List[str]c g}t|trt|ts|S|D]\}}t|ts||v}|s6|dr d|vr|d|d|dX|d}|r9t t |nd}|m||} t| |ot| tot|v } | s4|d|d|d|d t| j d |S) zValidate a plugin's config entry against its declared config_schema. Returns a list of human-actionable warning strings. Never raises; schema mismatches must not block plugin load (#64165). requiredrzplugins.entries.z .settings.z9 is required by the plugin's config_schema but is not setr;Nz should be z (got )) rrrCrrr6rrFrBr;r6) rXrPrYwarningsrQrRpresentrSexpectedroks r1validate_config_schemarb3sH fg & &j7.K.Kllnn d$((  (" xx ##  (=(=CyCCDCCC   CHR'++CJJ,<,<,>,>???d  TNEE8,,5$''@D,@2B ._resolve_depqs% Y  M{{6"""r3c,i|]}|tSr:)rrks r1 z-resolve_plugin_load_order..vs!9!9!9q!SUU!9!9!9r3rzPlugin %s requires plugin '%s' which is not enabled/installed; loading anyway (probe availability at runtime via ctx.has_plugin). Run `hermes plugins enable %s` if it is installed.z3Plugin %s declares a dependency on itself; ignoringrz^Plugin dependency cycle detected (%s); falling back to alphabetical load order for all pluginsz -> c34K|]}t|VdSrr=rcs r1rz,resolve_plugin_load_order..s(..1A......r3)rerr'rf)graphlibrDrErr(rrrrQrAaddTopologicalSorterprepare CycleErrorrrr is_active get_readyextenddone)rrqrErlrriedgesdepreresolvedsorterrcycleorderedreadyrhs` @r1resolve_plugin_load_orderr[sOOO ).."" # #D G |   D''GDM####### ":!9D!9!9!9E ##Q<0 # #C&0g&>&>HSWWT]]]DF #|F++H'vv 1}}TVWXXX !HLL " " " "# #& ' ' . .F   "38}}q00 b 6 KK..... . .    G     v''))**u U      NsD11 F&;A F!F&!F& source_textrfc.d|vsd|vrdSd|vrd|vrdSdS)aOReturn the plugin kind implied by source markers, or ``None``. Mirrors ``plugins/memory/__init__.py:_is_memory_provider_dir``: a module that registers a memory provider (``register_memory_provider`` or ``MemoryProvider``) belongs to the memory-provider discovery system (``exclusive``); a module that registers a model provider (``register_provider`` + ``ProviderProfile``) belongs to the providers discovery (``model-provider``). Applied to both directory plugins and pip entry-point plugins so neither is eagerly imported by the general PluginManager. register_memory_providerMemoryProviderrregister_providerProviderProfilerNr:)rs r1rrs@"[004D 4S4S{k)).?;.N.N 4r3 originlimitr0cB|sdS|dr2 tj|}n#t$rYdSwxYw|dsdS t |ddd|S#t$rYdSwxYw)aRead the first ``limit`` chars of a module's source file. Returns ``""`` on any failure (callers fall back to ``standalone``). ``.pyc``/``.pyo`` origins are mapped back to their source path so source is still scanned when only the bytecode cache is present. r<)z.pycz.pyo.pyrreplace)encodingerrorsN)endswithrutilsource_from_cacherr read_text)rrs r1_read_source_from_originrs r '(( ^55f==FF   22  ??5 ! !rF||%%wy%II&5&QQ rrs!; A A $+B BBrcd|dD}|sdS tj|d}||jsdSt |dkr|jS|j}|sdSt|dddD]\}}d}d}|D]q}t|}||z dz } | rt| }||z g}n.||d zz } | rt| }nr|dS|t |ks||cS|}dS#t$rYdSwxYw) uAReturn a module's source path WITHOUT importing it, or ``None``. ``importlib.util.find_spec`` on a dotted name imports the parent package first (executing its ``__init__.py``), which would run arbitrary package initialization during discovery and pay the very import cost this exists to avoid — a provider whose heavy imports live in ``package/__init__.py`` would still pay them. Only the top-level name is resolved with ``find_spec`` (import-free for top-level names); the remaining dotted segments are walked through ``submodule_search_locations`` by hand, mirroring the file layout conventions of the default PathFinder (``part.py`` module or ``part/__init__.py`` package). Namespace packages, zipped modules, extension modules, and anything else unexpected return ``None``. Shared with ``plugins/memory/__init__.py``, which needs the directory of a pip-installed provider to find its ``config_schema.py`` and ``cli.py`` — both of which are loaded by path precisely so the provider module never has to be imported. cg|]}||Sr:r:rps r1rz)resolve_module_origin..s 4 4 41! 4Q 4 4 4r3rNrrr.)start __init__.pyr) rrr find_specrrsubmodule_search_locations enumerater is_filerr) rpartsrR search_pathsipart found_origin next_pathsbasepkg_initmod_files r1resolve_module_originrs* 5 4 ))#.. 4 4 4E t~''a11 > GGGLLLMMMKKKKKr3rc(eZdZUdZded<ded<dS)_EventSubscriptionz%Host-owned subscription ledger entry.rownerr callbackNrr:r3r1rros-//JJJr3rcFeZdZUdZded<ded<ded<ded <ded <d S) _QueuedPluginEventz9Immutable dispatch envelope consumed by the event worker.reventr8payloadztuple[_EventSubscription, ...] subscriptionsr0depth generationNrr:r3r1rrwsICCJJJ1111JJJOOOOOr3rceZdZUdZded<dZded<eeZded <eeZ ded <eeZ ded <eeZ ded <d Z ded<dZ ded<d Zded<dS) LoadedPluginz)Runtime state for a single loaded plugin.rrNzOptional[types.ModuleType]modulerrZtools_registeredhooks_registeredmiddleware_registeredcommands_registeredFrBrrferrordeferred)r6r7r8r9rrrrrrrrrrrr:r3r1rrs33)-F----"'%"="="====="'%"="="=====',uT'B'B'BBBBB%*U4%@%@%@@@@@GEHr3rceZdZUdZded<ded<ded<dZded<ed d d Zd ed <ed d d Zded<e ddZ ddZ d S)PluginRegistrationamOne host-owned registration made while loading a plugin. Plugins only receive the context registration APIs; the manager owns the matching cleanup operation. Keeping that inverse operation beside the registration lets a force reload unwind global registries in reverse order, including an override that needs to restore the entry it replaced. rrrCallable[[], None]releaser< plugin_keyF)rinitreprrB _disposedNz0Optional[Callable[['PluginRegistration'], None]] _on_disposer'c|j S)z6Whether this handle still owns an active registration.)rselfs r1activezPluginRegistration.actives>!!r3rCc|jrdSd|_ ||j||dSdS#|j||wwxYw)z>Release this registration once; repeated disposal is harmless.NT)rrrrs r1disposezPluginRegistration.disposes} >  F ' LLNNN+  &&&&&,+t+  &&&&,s AA%r'rBr'rC) r6r7r8r9rrrrrpropertyrrr:r3r1rrsIII HHHJeEEBBBIBBBBDIE5uEEEK"""X" ' ' ' ' ' 'r3rz!^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$>modelr*securityrYz#^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$izDict[str, threading.RLock]_PLUGIN_STATE_LOCKStuple[str, ...]c8t|tstdt|d}|rBd|vs>d|vs:t d|Ds!|dtvrtd|S)a$Validate and split a plugin-relative settings key. The public API accepts only relative keys (``endpoint`` or ``retry.policy``). Full Hermes paths, traversal syntax, and the security- sensitive core roots called out in #64227 are rejected before any config read occurs. z,Expected a plugin-relative config key stringr/\c3LK|]}t| V dSr)_PLUGIN_SETTING_SEGMENT_REr)rsegments r1rz,_plugin_relative_segments..sE  BI*44W== =      r3rzExpected a plugin-relative config key such as 'endpoint' or 'retry.policy'; global, cross-plugin, and traversal paths are forbidden)rrr@tuplerrrF_PLUGIN_SETTING_RESERVED_ROOTS)rsegmentss r1_plugin_relative_segmentsrs c3  IGHHHSYYs^^$$H   #:: 3;;   MU       A;    "@ @ @ V    Or3rootrrc^|}|D]'}t|tr||vr|cS||}(|Sr)rr)rrrcurrentrs r1_nested_plugin_valuersLG##'7++ wg/E/ENNN'" Nr3dict[str, Any]c6|}t|D]}||i}|Sr)reversed)rrnestedrs r1_nested_plugin_mappingrs/FH%%##6" Mr3rc|p|}|r,|drtjd|r|St|S)zBReturn one Windows-safe directory component for plugin-owned data.rz[A-Za-z0-9][A-Za-z0-9_-]{0,191}) startswithrerr)rXr candidates r1_plugin_data_namespacersY,9I   1 1 L;Y G G  %Y / //r3rthreading.RLockct|d}t5t|t jcdddS#1swxYwYdS)NF)strict)rr._PLUGIN_STATE_LOCKS_GUARDr setdefault threadingRLock)rrs r1_state_thread_lockrs dll%l(( ) )C "FF"--c9?3D3DEEFFFFFFFFFFFFFFFFFFs,A$$A(+A(c #K|d|jd}t|}|5|jddt |d5}t jdkrddl}|dt j dkr)| d | |d| | |jd n1ddl}|| |j dVt jdkrD|d| | |jd n|| |jn#t jdkrD|d| | |jd w|| |jwxYwdddn #1swxYwYddddS#1swxYwYdS) aSerialize state read-modify-write across threads and processes. ``fcntl`` is used on POSIX and ``msvcrt`` on native Windows. The lock is kept in a sibling file because atomic replacement changes the inode/file handle of the target itself. rz.lockTparentsexist_okza+bntrNr) with_namerrr/mkdiropenr+msvcrtseekSEEK_ENDwriteflushlockingfilenoLK_LOCKfcntlflockLOCK_EXLK_UNLCKLOCK_UN)r lock_path thread_lockhandlerrs r1_locked_plugin_staters34933344I$Y//K @@td;;; )U # # @vw$ ;;q"+..!33LL'''LLNNN Av}}BBBB  FMMOOU];;; @7d??KKNNNNN6==??FOQGGGGKK ???? 7d??KKNNNNN6==??FOQGGGGKK ????) @ @ @ @ @ @ @ @ @ @ @ @ @ @ @@@@@@@@@@@@@@@@@@@sP-I'CI7F=;BI=BII I'I I'I I''I+.I+ceZdZdZdddZedd Zedd Zedd Ze ddZ ddZ dddZ d dZ dS)! PluginStatez?Atomic, quota-bounded JSON key/value state owned by one plugin.r<rXrrr'rCc0t|||_dSr)r_data_namespace)rrXrs r1__init__zPluginState.__init__+s5iQQr3r c4tdz |jz S)z@Profile-scoped directory matching portable plugins' PLUGIN_DATA. plugin-data)rr"rs r1data_dirzPluginState.data_dir.s  =043GGGr3c|jdz S)Nz state.json)r&rs r1rzPluginState.path3s}|++r3r0ctSr)_PLUGIN_STATE_QUOTA_BYTESrs r1 quota_byteszPluginState.quota_bytes7s((r3rct|trt|rd|vrt ddS)Nz..zgPlugin state keys must be 1-128 characters using letters, numbers, '_', '-', '.', or ':' (without '..'))rr_PLUGIN_STATE_KEY_RErr@)rs r1 _validate_keyzPluginState._validate_key;sV3$$ '11#66 s{{@ {r3rcj t|jd5}tj|}dddn #1swxYwYnA#t$ricYSt t f$r }td|jd||d}~wwxYwt|tstd|jd|S)NrrzCannot parse plugin state z: z: root must be an object) r rjsonloadFileNotFoundErrorOSErrorr@ RuntimeErrorrr)rrr7rs r1_read_unlockedzPluginState._read_unlockedGs! Ydi'222 )fy(( ) ) ) ) ) ) ) ) ) ) ) ) ) ) )    III$ Y Y YNDINNNNOOUX X Y$%% PTYPPP  s:A9 A=A=A BB#A>>BNrr c||t|j5|||cdddS#1swxYwYdS)z>Read a JSON value, returning *default* when the key is absent.N)r-rrr5r)rrrs r1rzPluginState.getUs 3 !$) , , ; ;&&((,,S':: ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ;s(AA#&A#rc ||t|j5|}|||< t j|ddd}n-#ttf$r}td|d|d}~wwxYwt||j kr(tdt|d |j d d d l m }||j|d ddddS#1swxYwYdS)zBAtomically set one JSON value without dropping concurrent updates.Fr.) ensure_asciiindentrzPlugin state value for z is not JSON-serializableNzPlugin state quota exceeded: z bytes is greater than the z-byte per-plugin quotar)atomic_json_writei)mode) r-rrr5r0dumpsr r?r@rr*utilsr:)rrrr7encodedrr:s r1rzPluginState.set[s 3 !$) , , ; ;&&((DDI *TaHHHOOPWXXz*    NcNNN 7||d... ICLLII $ 0III 0 / / / / /  diE : : : :! ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ; ;s6D*A0/D0BBBADD D)r<)rXrrrr'rCr'r r'r0)rrr'rC)r'rrrrrr r'r rrrr r'rC)r6r7r8r9r#rr&rr* staticmethodr-r5rrr:r3r1r r (sIIRRRRRHHHXH,,,X,)))X)   \     ;;;;; ;;;;;;r3r cZeZdZdZddZedd Zdd ZdddZddZ eddZ edZ ddZ d ddd&Z edd'Zedd(Zedd)Zdd+Zd d,dd0Zdd3Ze dddCZddEZ dddNZdOZeddQZeddSZddUZ dd dWdd\Zdd]Ze dddaZ e dddcZ!ddeZ"eddfZ#ddgZ$ddhZ%eddiZ&eddjZ'eddkZ(eddlZ)eddmZ*eddnZ+eddoZ,eddpZ-e dddwZ.ddyZ/dd{Z0ed d|ddZ1ddZ2ddZ3de4dddZ5dddZ6ddZ7ddZ8e dddZ9d S) PluginContextz=Facade given to plugins so they can register tools and hooks.rrmanager'PluginManager'cZ||_||_d|_d|_d|_d|_dSr)r_manager_llm_subagent_lifecycle_state_platform_actions)rrrFs r1r#zPluginContext.__init__ts4    (, *. &*r3r'rc2|jjp |jjS)zCReturn the effective registry id used for this plugin's namespaces.)rrrrs r1rXzPluginContext.plugin_id~s} 6DM$66r3rXrBc|jjD]&\}}|js ||ks|jj|krdS'dS)a&Return True when another plugin is loaded and enabled (#64165). Companion to the advisory ``requires_plugins`` manifest field: a missing dependency never blocks load, so plugins probe availability at runtime with this. Matches on registry key or manifest name. TF)rI_pluginsrCrrr)rrXrloadeds r1 has_pluginzPluginContext.has_pluginsa =17799  KC> i6?#79#D#Dtt$Eur3Nrrr c t|}n0#t$r#td||jwxYwddlm}|pi}t|tr| dnd}t|tr| dnd}t|tr| |jnd}t|ts|St} t| d|| } | | ur| St| d||S) aRead ``plugins.entries..settings.``. ``key`` is always plugin-relative. For migration compatibility, a missing canonical value falls back to the former ``config`` subtree; no global config paths are exposed. &Rejected config path %r from plugin %sr)rr*NentriesrYr) rr@rQrArXrrrrrrr) rrrrrrr*rUentrymissingrs r1 get_configzPluginContext.get_configsY 055HH    NN8#t~       ;:::::%%''-2+5fg+F+FP&**Y'''D,6w,H,HR'++i(((d/9'7/K/KU DN+++QU%)) N(($UYYz%:%:HgNN   L#EIIh$7$77KKKs-?rrCc t|}n0#t$r#td||jwxYwddlm}|rtdddlm }d dd|jd g|R}| |rtd |d dd|jd t||iiii}dd|jd g|R}t|5|j5||||hd dddn #1swxYwYddddS#1swxYwYdS)zAAtomically write one value in this plugin's ``settings`` subtree.rTrrz6Plugin settings cannot be changed in a managed install) managed_scoperr*rUrYzPlugin setting z is administrator-managedT) preserve_keysmerge_existingN)rr@rQrArX hermes_clir is_managedPermissionErrorr[ris_key_managedrrget_config_path _CONFIG_LOCKread_user_config_raw save_config) rrrr config_modr[ dotted_pathpartial full_paths r1 set_configzPluginContext.set_configsz 055HH    NN8#t~       433333  " " !H  -,,,,,hh   N          ' ' 4 4 !J+JJJ  N"$:8U$K$K%  4>:QQQ "*"<"<">"> ? ?  (  //111&&#,+#''                                 s>-?E .E< E E E E E  E$'E$r cf|j$t|j|jj|_|jS)z>Return this plugin's profile-scoped durable JSON state facade.)rLr rXrrrs r1statezPluginContext.states, ; %dndm6STTDK{r3cT|jddlm}||j|_|jS)uCapability-gated platform action facade (#64176, v1). Minimal verb set (``add_reaction``, ``set_thread_title``) routed through the live gateway adapter registry. Every call re-checks the ``gateway.platform_actions`` capability (legacy gate: ``plugins.entries..allow_platform_actions``, default OFF) and returns a structured ``{"ok": bool, ...}`` dict — verbs never raise into hook dispatch. No adapter handles or raw SDK objects are exposed. Nr)PlatformActions)rMhermes_cli.platform_actionsrnrX)rrns r1platform_actionszPluginContext.platform_actionss<  ! ) C C C C C C%4_T^%D%DD "%%r3rrrrcF|j|j|||S)z8Record host-owned cleanup for a successful registration.)rI_track_registrationr)rrrrs r1_trackzPluginContext._tracks)}00 M4g   r3)finalizeslotrrpreviousrestoreCallable[[Any], bool]rtOptional[Callable[[], None]]cltj|||||}||||jS)z8Track one generation in a replaceable registration slot.rrvrwrt)racquirersr) rrrrurrvrwrtleases r1_track_replacementz PluginContext._track_replacement sD(/     {{4em444r3c||j/ddlm}|jjp |jj}|||_|jS)aReturn the plugin's :class:`agent.plugin_llm.PluginLlm` facade. Lets trusted plugins run host-owned chat or structured completions against the user's active model and auth without bringing their own provider keys. Override capability (model, agent id, auth profile) is fail-closed by default and gated through ``plugins.entries..llm.*`` config keys. See :mod:`agent.plugin_llm` for the full surface.Nr) PluginLlmrX)rJagent.plugin_llmrrrr)rrrXs r1llmzPluginContext.llm!sN 9  2 2 2 2 2 2 )?T]-?I! I666DIyr3cN|jddlm}m}|||_|jS)a(Return the public, plugin-safe subagent lifecycle service. The service only resolves the active host-owned parent agent when a child is launched. Plugins receive serializable handles and immutable snapshots; they never receive a live agent or a private registry. Nr)SubagentLifecycleServiceget_active_subagent_parent)rKagent.subagent_lifecyclerr)rrrs r1subagent_lifecyclez PluginContext.subagent_lifecycle2s[  # +        (@'?*((D $''r3cF ddlm}|S#t$rYdSwxYw)uXReturn the active Hermes profile name (e.g. ``"default"``). Derived from ``HERMES_HOME`` via :func:`hermes_cli.profiles.get_active_profile_name`, so it works in every execution context — interactive CLI, gateway, and kanban-spawned worker sessions alike — without depending on ``_cli_ref`` (which is ``None`` outside an interactive CLI run). Returns ``"default"`` for the default profile, the profile id when running under ``~/.hermes/profiles/``, or ``"custom"`` when ``HERMES_HOME`` points somewhere unrecognized. r)get_active_profile_namer)hermes_cli.profilesrr)rrs r1 profile_namezPluginContext.profile_nameFsJ  C C C C C C**,, ,   99 s   rct|std|dt|dd|}td|jj|S)u`Register a cleanup callback that runs when this plugin unloads. Callbacks are recorded in the ownership ledger, so they run in reverse acquisition order interleaved with registration teardown, and each is isolated — an exception is logged, never propagated (see :meth:`PluginManager._dispose_registrations`). z#on_unload callback must be callable on_unloadr6rz'Plugin %s registered on_unload callback)callabler?rsrrQrTrr)rrrs r1rzPluginContext.on_unload\se!! CABB B['(J *S*SU]^^ > @RSSS r3rrrf'asyncio.Task'cttj|stdtj}|p d|jd}|||d fd }|d||fd t d |j j |S) zSpawn a supervised background asyncio task owned by this plugin. The task is recorded in the ownership ledger; unloading the plugin (or a force reload) cancels it. Requires a running event loop. zspawn_task expects a coroutineplugin:z:taskrr'rCc\sdSdSr)rycancel)tasksr1 _cancel_taskz.PluginContext.spawn_task.._cancel_taskvs.99;;    r3background_taskc,Sr)r)_trs r1z*PluginContext.spawn_task..{s&..*:*:r3z%Plugin %s spawned supervised task: %sr) asyncio iscoroutiner?get_running_looprX create_taskrsadd_done_callbackrQrTrr)rcororloop task_namerrrs @@r1 spawn_taskzPluginContext.spawn_taskjs "4(( ><== ='));;dn;;; 955      . <HH ::::;;; 3T]5G    r3 present_fnr c j||jjp jjt |jj < ddtjjfdfddSdS)aRegister a human approval presentation transport. The transport is inactive until the operator explicitly selects ``security.approval.transport: ``. It receives a host-created, redacted ``ApprovalRequest`` and may only return a correlated human decision; command policy and approval persistence remain host-owned. ``present_fn`` may be synchronous or async. rNapproval_transportmanager_mappingcRjjj|Sr)rI_restore_mapping_approval_transports replacementcleanrVrs r1rz;PluginContext.register_approval_transport..s'DM,J,JM6uk--r3rurrvrw) rIregister_approval_transportrrrrrErFrrr~r)rrrrrVs` @@r1rz)PluginContext.register_approval_transports 11  m'=4=+= 2   D !!'')) 266u==    # #$%t}9::  $       r3Fr<toolsetrPrrUcheck_fnCallable | Noner" list | Noneis_asyncremojioverrideOptional[PluginRegistration]c | rPs;jjp jj} t djjdd| dddlmjj }  } | ,| *| s(t d jjdS |||||||| |   Y| urUj|urLjjdfd }ddf| |fd}nd}tdjj| rdnd|S)uSRegister a tool in the global registry **and** track it as plugin-provided. Pass ``override=True`` to replace an existing built-in tool with the same name (e.g. swap the default ``browser_navigate`` for a custom CDP-backed implementation). Without it, attempting to register a name already claimed by a different toolset is rejected. ``override=True`` against a built-in tool requires the operator to opt in via ``plugins.entries..allow_tool_override: true`` in config.yaml — mirrors the trust gate pattern used for ``ctx.llm`` provider/model overrides (#23194). Without that gate, any enabled plugin could silently replace a privileged built-in like ``shell_exec`` or ``write_file`` and exfiltrate everything the model invokes through it. Plugin z cannot override built-in tool z. Set plugins.entries.zY.allow_tool_override: true in config.yaml to allow this plugin to replace built-in tools.rregistryscopeNz>Plugin %s tried to shadow global tool %s without override=True) rrrPrUrr"rrrrrrr r'rBc6|SNrrestore_registration)rr registeredrrs r1 _restore_toolz2PluginContext.register_tool.._restore_tools)44*k5r3toolc8jSr)rI_remove_tool_name_if_unownedrrsr1rz-PluginContext.register_tool..s!K!KD!Q!Qr3rurrvrwrtzPlugin %s registered tool: %s%sz (override)r<)rr r'rB)_tool_override_allowedrrrr5tools.registryrrI scope_keysnapshot_registration get_entryrQrAregisterrU_plugin_tool_namesrrr~rT)rrrrPrUrr"rrrrrXrv effectiverrrrrs`` @@@r1 register_toolzPluginContext.register_toolsQ:  D77==  )?T]-?I)R$-,RRRR#,RRR  ,+++++ '11$e1DD&&t5&99   5h 5 NNP "    4%#  33D3FF  "(**"g-- M , 0 0 6 6 6          ,,eT*"!%QQQQQ-FFF - M x&GmmR    r3rct|jddpd}|dkr|dkrdS|jjp |jj}t ||S)aReturn True when *capability* is live for this plugin. Plugins should probe with this and degrade gracefully instead of crashing when a gated host surface refuses them. Bundled plugins are trusted for ``tools.override`` (mirrors the registration gate); for everything else the answer comes from the granted-capability set or the deprecated legacy ``allow_*`` config key. Unknown capability ids and unreadable consent state return False (fail closed). rr<bundledtools.overrideT)rrrrr")rrrrXs r1has_capabilityzPluginContext.has_capabilitys["55; Y  :1A#A#A4M%;); (J???r3serverr argumentsOptional[Dict[str, Any]]timeoutr2r8c .|jjp |jj}||}||vr#t d|jjd|d|d t |}n#t tf$rd}YnwxYwtdt|d}dd l m }||||}|t|pi} td |jj|||t| pd || S) uCall a tool on a configured MCP server (#64204, capability-gated). Synchronous; safe to call from plugin hooks and tools. Routes through the EXISTING native MCP client machinery in :mod:`tools.mcp_tool` (background loop, trust-tier gates, circuit breaker, reconnect and result rendering) — never a parallel client or connection. Default-off: a plugin has NO MCP access until the operator lists the servers it may reach under ``plugins.entries..mcp_allowlist`` in config.yaml:: plugins: entries: my-plugin: mcp_allowlist: ["knowledge_rag", "github"] Calls to unlisted servers raise :class:`PermissionError`. This is a per-server grant, deliberately not ambient authority over every configured server. # TODO(#64228): swap the per-server allowlist for the declared # capability model once it lands (per-tool grants, expiry, ro/rw). Args: server: MCP server name as configured in ``mcp.servers``. tool: Tool name on that server (unprefixed). arguments: JSON-serializable arguments dict for the tool. timeout: Seconds to wait for the call (default 30) so a hung MCP server can never stall the hook/tool pipeline. Returns: Envelope dict: ``{"ok": True, "result": }`` on success or ``{"ok": False, "error": }`` when the MCP call itself failed. Results larger than ~64KB are truncated with a marker. Raises: PermissionError: server not in this plugin's ``mcp_allowlist``. rz# is not allowed to call MCP server z. Add it to plugins.entries.zI.mcp_allowlist in config.yaml to grant access (default is no MCP access).>@g?g@r)_make_tool_handlerz;Plugin %s called MCP %s/%s (timeout=%ss, %d chars returned)r<)rrr_mcp_allowlistr`r2r?r@maxmintools.mcp_toolrrrQrTr _mcp_envelope) rrrrrrX allowlistrrUraws r1call_mcpzPluginContext.call_mcps^ZM%;); '' 22  " "!?$-,?? ??#,???  GnnGG:&   GGG c3w..// 655555$$VT7;;gd9?++,, I M gs39"~~   !!#&&&sA&&A<;A<irct|ts|dnt|}t||jkr|d|jdz}d}nd}d} t j|}n#t tf$rd}YnwxYwt|trd|vr d|dd}n=t|trd|vrd|dd }d |vr |d |d <n d||n|d }|rd|d <|S) z>Normalize an MCP handler result string into a stable envelope.Nr<u… [truncated]TFr)rarresult)rarstructuredContent truncated) rrr_MCP_RESULT_CHAR_CAPr0loadsr@r?r)clsrrparsedenvelopes r1rzPluginContext._mcp_envelopedsN#s## 2 ""SC s88c. . .00014EECIII Z__FFI&   FFF  fd # # U6(9(9.3fWo'N'NHH  % % U(f*<*<"fX.>??H"f,,067J0K,-"8JffPSTTH  )$(H[ !sA00BBrZcD ddlm}|pi}n#t$rgcYSwxYw|dpidpi}||pi}|d}t |t sgSd|DS)uReturn the operator-granted MCP server allowlist for a plugin. Missing key or unreadable config → empty list (fail closed, default-deny). rrr*rU mcp_allowlistc,g|]}t|Sr:r=rs r1rz0PluginContext._mcp_allowlist..s000dD 000r3)rrrrrr)rXrcfgrUrVrs r1rzPluginContext._mcp_allowlists  5 5 5 5 5 5+--%2CC   III 779%%+00;;Ar I&&,"IIo.. )T** I00i0000s  $$ tool_namecBt|jddpd}|dkrdS ddlm}t |jj5|pi}dddn #1swxYwYn#t$rYdSwxYw|jjp |jj }t|d | S) uReturn True if this plugin is configured to override built-in tools. Bundled plugins (shipped with Hermes core) are trusted by default — an override there is a deliberate maintainer choice, not a third-party plugin trying to elevate privilege. For every other source, the canonical check is :func:`plugin_capability_granted` with the ``tools.override`` capability — satisfied by EITHER the consent-flow grant (``plugins.entries..granted_capabilities``) OR the deprecated legacy key ``allow_tool_override: true`` (still honored for backward compatibility; #64228 reference migration). rr<rTrrNFrrZ) rrrrrrI home_pathrrrr")rrrrrrXs r1rz$PluginContext._tool_override_alloweds"55; Y  4  5 5 5 5 5 5#DM$;<< * *!kmm)r * * * * * * * * * * * * * * *   55 M%;); )4DSQQQQs5A& A A&AA&!A"A&& A43A4user) session_keyrroler str | Nonec|jj}|dkr|nd|d|}|Ht|ddr|j|n|j|dS|st ddS|s6|j j p |j j }t d ||dS|jj st d dS|j j p |j j } t|j||| S#t$r!t d |d YdSwxYw)aInject a message into a CLI or gateway conversation. If the agent is idle (waiting for user input), this starts a new turn. If the agent is running, this interrupts and injects the message. This enables plugins (e.g. remote control viewers, messaging bridges) to send messages into the conversation from external sources. Gateway injection requires an existing ``session_key`` and an explicit ``plugins.entries..allow_gateway_injection`` config grant. A ``True`` return means the live gateway accepted the request for asynchronous dispatch, not that platform delivery has completed. Returns True if the message was queued successfully. r[z] N_agent_runningFTz=inject_message: gateway mode requires an existing session_keyzxinject_message: gateway injection denied for plugin %s; set plugins.entries.%s.allow_gateway_injection: true to allow itz,inject_message: no live gateway is available)rrrXz7inject_message: gateway scheduling failed for plugin %sexc_info)rI_cli_refr_interrupt_queueput_pending_inputrQrA_gateway_injection_allowedrrrhas_gateway_message_injectorrBinject_gateway_messager)rrrrclimsgrXs r1inject_messagezPluginContext.inject_messages,m$gg-B-B-B-B-B ?s,e44 ,$((----"&&s+++4  NNO   5..00  )?T]-?I NNO     5}9  NNI J J J5M%;);   44 +'5     NNI     55  s)D::'E%$E%c tpi}n#t$rYdSwxYw|jjp |jj}t |dd|ddduS)z=Return whether this plugin may trigger gateway session turns.Fr*rUallow_gateway_injectionrT)rrrrrr)rrrXs r1rz(PluginContext._gateway_injection_alloweds &((.BCC   55 M%;); )      s  !!helpsetup_fn handler_fnc |jj}||||jjjjp jjdjj<ddtjjf|fd}t djj|S)aRegister a CLI subcommand (e.g. ``hermes honcho ...``). The *setup_fn* receives an argparse subparser and should add any arguments/sub-subparsers. If *handler_fn* is provided it is set as the default dispatch function via ``set_defaults(func=...)``.)rr rr r rr cli_commandrcRjjj|Sr)rIr _cli_commands)rrVrrs r1rz4PluginContext.register_cli_command..0s' (F(F +T5+))r3rz$Plugin %s registered CLI command: %s) rIrrrrrr~rrQrT) rrr r r rrvrrVs `` @r1register_cli_commandz"PluginContext.register_cli_commands=.22488& $m(-+At}/A  -2 #D)((  #R (C%D%DdK )     ;T]=OQUVVV r3 args_hintc & |ddds'tdjjdS ddlm }|(tdjjdSn#t$rYnwxYwj j }||pd jjjjp jj|pd d  j j <d d t!j j f | fd}tdjj|S)uRegister a slash command (e.g. ``/lcm``) available in CLI and gateway sessions. The handler signature is ``fn(raw_args: str) -> str | None``. It may also be an async callable — the gateway dispatch handles both. Unlike ``register_cli_command()`` (which creates ``hermes `` terminal commands), this registers in-session slash commands that users invoke during a conversation. ``args_hint`` is an optional short string (e.g. ``""`` or ``"dias:7 formato:json"``) used by gateway adapters to surface the command with an argument field — for example Discord's native slash command picker. Plugin commands without ``args_hint`` register as parameterless in Discord and still accept trailing text when invoked as free-form chat. Names conflicting with built-in commands are rejected with a warning. r rz;Plugin '%s' tried to register a command with an empty name.Nr)resolve_commandz^Plugin '%s' tried to register command '/%s' which conflicts with a built-in command. Skipping.zPlugin commandr<)rUrrrrcommandrcRjjj|Sr)rIr_plugin_commandsrs r1rz0PluginContext.register_command..ws' (F(F .uk))r3rz!Plugin %s registered command: /%s)rFrElstriprrQrArrhermes_cli.commandsrrrIrrrr~rrT) rrrUrrrrvrrrVs ` @@r1register_commandzPluginContext.register_command9s4 ""$$++C0088cBB  NNM "    F  ; ; ; ; ; ;u%%19M&  2    D =155e<<&:*:m(-+At}/A#/r0022   16 &u-((  #R (F%G%GO )     8$-:LeTTT s;7B55 CCrc ddlm}d|vr(|jj}|rt |ddnd}|||d<|j||fd|jji|S)uDispatch a tool call through the registry, with parent agent context. This is the public interface for plugin slash commands that need to call tools like ``delegate_task`` without reaching into framework internals. The parent agent (if available) is resolved automatically — plugins never need to access the agent directly. Args: tool_name: Registry name of the tool (e.g. ``"delegate_task"``). args: Tool arguments dict (same as what the model would pass). **kwargs: Extra keyword args forwarded to the registry dispatch. Returns: JSON string from the tool handler (same format as model tool calls). rr parent_agentagentNr)rrrIrrdispatchr)rrrrrrrs r1 dispatch_toolzPluginContext.dispatch_tools ,+++++  ' '-(C36@GC$///DE ).~& x t  #'=#: >D   r3c jj'tdjjdSddlm}t|s'tdjjdSjj}j_ djdtjdf|fd  }t d jjj|S) a%Register a context engine to replace the built-in ContextCompressor. Only one context engine plugin is allowed. If a second plugin tries to register one, it is rejected with a warning. The engine must be an instance of ``agent.context_engine.ContextEngine``. NzyPlugin '%s' tried to register a context engine, but one is already registered. Only one context engine plugin is allowed.r) ContextEnginezbPlugin '%s' tried to register a context engine that does not inherit from ContextEngine. Ignoring.context_engine manager_value_context_enginec<jd|S)Nr&)rI_restore_value)renginers r1rz7PluginContext.register_context_engine..s  (D(D!6;))r3rz)Plugin '%s' registered context engine: %s) rIr&rQrArragent.context_enginer#rr~rinfo)rr)r#rvrs`` r1register_context_enginez%PluginContext.register_context_engines" = ( 4 NNQ "    F666666&-00  NN8 "    F=0(. %((  K!2dm#4#46GH )     7 M      r3cpddlm}m}t||s'td|jjdS ||n>#t$r1}td|jj|Yd}~dSd}~wwxYwt d|jj|j dS)aRegister a custom @-prefix context reference provider. ``provider`` must be an instance of :class:`agent.context_references.ContextReferenceProvider`. The ``provider.prefix`` attribute defines the @-prefix (e.g. ``"issue"`` creates ``@issue:...``). Built-in prefixes (diff, staged, file, folder, git, url) are reserved and will be rejected. r)ContextReferenceProvider#register_context_reference_providerzyPlugin '%s' tried to register a context reference provider that does not inherit from ContextReferenceProvider. Ignoring.Nz5Plugin '%s' context reference registration failed: %sz.Plugin '%s' registered context reference: @%s:) agent.context_referencesr.r/rrQrArrr@r+prefix)rprovider_CRP _registerrs r1register_context_referencez(PluginContext.register_context_references        (D))  NNQ "    F  Ih        NNG "C    FFFFF    < M      s A B&BBc ddlm}t||s'td|jjdS||_td|jjt|dddS)uRegister a memory provider. Memory providers are activated exclusively, by name, through ``memory.provider`` in config.yaml, and ``plugins/memory/__init__.py`` owns that path with its own collector. A provider reaching *this* implementation is therefore one the general PluginManager loaded — it was not classified ``exclusive`` — so the call is recorded and otherwise inert. Without it, such a plugin's ``register()`` dies on a missing attribute and the plugin fails to load at all. Memory was the only provider category with no ``register_*`` here, which is what made that failure mode possible. The provider must be an instance of ``agent.memory_provider.MemoryProvider``. r)rzdPlugin '%s' tried to register a memory provider that does not inherit from MemoryProvider. Ignoring.Nz*Plugin '%s' registered memory provider: %srr) agent.memory_providerrrrQrArr_memory_providerrTr)rr2rs r1rz&PluginContext.register_memory_providers 988888(N33  NN9 "    F ( 8 M &# > >     r3c  ddlm}ddlm}m m}t |s'td|j j dSj |j j | }| | }|urdS|dd f| fd }td |j j |S) a=Register an image generation backend. ``provider`` must be an instance of :class:`agent.image_gen_provider.ImageGenProvider`. The ``provider.name`` attribute is what ``image_gen.provider`` in ``config.yaml`` matches against when routing ``image_generate`` tool calls. r)ImageGenProviderrrrzjPlugin '%s' tried to register an image_gen provider that does not inherit from ImageGenProvider. Ignoring.Nrimage_gen_providerc"|Srr:rr2 registry_namerrs r1rz;PluginContext.register_image_gen_provider..7 #(<(<xE)))r3rz-Plugin '%s' registered image_gen provider: %s)agent.image_gen_providerr:agent.image_gen_registryrrrrrQrArrrErIrr~r+) rr2r:rrrvrrr?rrs ` @@@r1register_image_gen_providerz)PluginContext.register_image_gen_provider sw >=====          ($455  NN? "    F ++--  '((eDDD(%0000**=FFF X % %4(( &}= )     ; M      r3c r ddlm}m}ddlm ddlm}t |s'td|j j dSj |j j | } | nU#ttf$rA}td|j j td d |Yd}~dSd}~wwxYw| }|urdS|d d f| fd  }td|j j j|S)u$Register a dashboard authentication provider. ``provider`` must be an instance of :class:`hermes_cli.dashboard_auth.DashboardAuthProvider`. Used by the dashboard OAuth auth gate, which engages when the dashboard binds to a non-loopback host without ``--insecure``. Misbehaving providers (wrong type, duplicate name) are logged at WARNING and silently ignored — never raised — so a broken plugin cannot crash the host. Same convention as ``register_image_gen_provider``. r)DashboardAuthProviderrr)rzsPlugin '%s' tried to register a dashboard-auth provider that does not inherit from DashboardAuthProvider. Ignoring.Nrz=Plugin '%s' failed to register dashboard-auth provider %r: %srrdashboard_auth_providerc"|Srr:r>s r1rz@PluginContext.register_dashboard_auth_provider..t r@r3rz7Plugin '%s' registered dashboard-auth provider: %s (%s))hermes_cli.dashboard_authrEr"hermes_cli.dashboard_auth.registryrrrrQrArrrIrr?r@rr~r+ display_name) rr2rErrrverrr?rrs ` @@@r1 register_dashboard_auth_providerz.PluginContext.register_dashboard_auth_providerC s         LKKKKKLLLLLL($9::  NNN "    F  '((eDDD   he 4 4 4 4 4:&    NN "GHfc$B$BA    FFFFF  +*=FFF X % %4(( % +UMB )     E M  x/D    s1 A??C6C  Cc  ddlm}ddlm}m m}t |s'td|j j dSj |j j | }| | }|urdS|dd f| fd }td |j j |S) a<Register a video generation backend. ``provider`` must be an instance of :class:`agent.video_gen_provider.VideoGenProvider`. The ``provider.name`` attribute is what ``video_gen.provider`` in ``config.yaml`` matches against when routing ``video_generate`` tool calls. r)VideoGenProviderr;ziPlugin '%s' tried to register a video_gen provider that does not inherit from VideoGenProvider. Ignoring.Nrvideo_gen_providerc"|Srr:r>s r1rz;PluginContext.register_video_gen_provider.. r@r3rz-Plugin '%s' registered video_gen provider: %s)agent.video_gen_providerrNagent.video_gen_registryrrrrrQrArrrErIrr~r+) rr2rN_register_video_providerrrvrrr?rrs ` @@@r1register_video_gen_providerz)PluginContext.register_video_gen_provider sw >=====          ($455  NN? "    F ++--  '((eDDD  7777**=FFF X % %4(( &}= )     ; M      r3c  ddlm}ddlm}m m}t |s'td|j j dSj |j j | }| | }|urdS|dd f| fd }td |j j |S) aRegister a web search/extract backend. ``provider`` must be an instance of :class:`agent.web_search_provider.WebSearchProvider`. The ``provider.name`` attribute is what ``web.search_backend`` / ``web.extract_backend`` / ``web.backend`` in ``config.yaml`` matches against when routing ``web_search`` / ``web_extract`` tool calls. r)WebSearchProviderr;zdPlugin '%s' tried to register a web provider that does not inherit from WebSearchProvider. Ignoring.Nrweb_search_providerc"|Srr:r>s r1rz. r@r3rz'Plugin '%s' registered web provider: %s)agent.web_search_providerrVagent.web_search_registryrrrrrQrArrrErIrr~r+) rr2rV_register_web_providerrrvrrr?rrs ` @@@r1register_web_search_providerz*PluginContext.register_web_search_provider sy @?????          ($566  NN@ "    F ++--  '((eDDDxu5555**=FFF X % %4(( ! ' > )     5 M      r3c  ddlm}ddlm}m m}t |s'td|j j dSj |j j | }| | }|urdS|dd f| fd }td |j j |S) uQRegister a cloud browser backend. ``provider`` must be an instance of :class:`agent.browser_provider.BrowserProvider`. The ``provider.name`` attribute is what ``browser.cloud_provider`` in ``config.yaml`` matches against when routing cloud-mode ``browser_*`` tool calls. Mirrors :meth:`register_web_search_provider` exactly — same registration shape, same gating, same logging. The browser subsystem's dispatcher (:func:`tools.browser_tool._get_cloud_provider`) consults the registry built up by these calls. r)BrowserProviderr;zfPlugin '%s' tried to register a browser provider that does not inherit from BrowserProvider. Ignoring.Nrbrowser_providerc"|Srr:r>s r1rz9PluginContext.register_browser_provider.. r@r3rz+Plugin '%s' registered browser provider: %s)agent.browser_providerr^agent.browser_registryrrrrrQrArrrErIrr~r+) rr2r^_register_browser_providerrrvrrr?rrs ` @@@r1register_browser_providerz'PluginContext.register_browser_provider sv ;:::::          (O44  NN> "    F ++--  '((eDDD""859999**=FFF X % %4((  $e]; )     9 M      r3c  ddlm}ddlm}m m}t |s'td|j j dSj |j j | }| r_| }|urdS| dd f| fd }td |j j |SdS) uRegister an external secret-manager backend. ``source`` must be an instance of :class:`agent.secret_sources.base.SecretSource`. Registered sources run during ``load_hermes_dotenv()`` startup — after ``~/.hermes/.env`` loads, before Hermes reads credentials — when their ``secrets.`` config section is enabled. The orchestrator (``agent.secret_sources.registry.apply_all``) owns ordering, mapped-vs-bulk precedence, conflict warnings, and provenance; the source only fetches. NOTE ON TIMING: ``load_hermes_dotenv()`` usually runs at import *before* plugin discovery. After discovery completes, the plugin manager re-pulls enabled plugin secret sources (``reset_secret_source_cache`` + ``load_hermes_dotenv``) so the first process sees them (#64177). Child processes that load env after plugins still work without that re-pull. Failed re-pulls never block startup. Contract requirements (rejected with a warning otherwise): inherit from ``SecretSource``, ``api_version`` matching ``SECRET_SOURCE_API_VERSION``, lowercase unique ``name``, ``shape`` of ``"mapped"`` or ``"bulk"``, unique ``scheme`` (when set), and a ``fetch()`` that never raises and never prompts. See the base-module docstring for the full contract. r) SecretSource)register_sourcerrz`Plugin '%s' tried to register a secret source that does not inherit from SecretSource. Ignoring.Nr secret_sourcec"|Srr:)rr?rrrs r1rz6PluginContext.register_secret_source..O s#,@,@!6;e---r3rz(Plugin '%s' registered secret source: %s)agent.secret_sources.baserfagent.secret_sources.registryrgrrrrQrArrrIrr~r+) rrrfrgrrvrrr?rrs ` @@@r1register_secret_sourcez$PluginContext.register_secret_source sp6 ;:::::          &,//  NN; "    F  '((eDDD ?6 / / / ..}EJJJJ''t,,%um<! -  F KK: "M   Mtr3c  ddlm}ddlm}m m}t |s'td|j j dSj |j j | }| | }|urdS|dd f| fd }td |j j |S) u|Register a text-to-speech backend. ``provider`` must be an instance of :class:`agent.tts_provider.TTSProvider`. The ``provider.name`` attribute is what ``tts.provider`` in ``config.yaml`` matches against when routing ``text_to_speech`` tool calls — **but only when**: 1. ``provider.name`` is NOT a built-in TTS provider name (``edge``, ``openai``, ``elevenlabs``, …). Built-ins always win — the registry rejects shadowing names with a warning. 2. There is NO ``tts.providers.: type: command`` entry with the same name. Command-providers (PR #17843) win on name collision because config is more local than plugin install. Coexists with the command-provider registry rather than replacing it — see issue #30398 for the full design rationale. r) TTSProviderr;z^Plugin '%s' tried to register a TTS provider that does not inherit from TTSProvider. Ignoring.Nr tts_providerc"|Srr:r>s r1rz5PluginContext.register_tts_provider.. r@r3rz'Plugin '%s' registered TTS provider: %s)agent.tts_providerrnagent.tts_registryrrrrrQrArrrErFrIrr~r+) rr2rn_register_tts_providerrrvrrr?rrs ` @@@r1register_tts_providerz#PluginContext.register_tts_provider\ s* 322222          (K00  NN: "    F ++--3355  '((eDDDxu5555**=FFF X % %4((   %7 )     5 M      r3c  ddlm}ddlm}m m}t |s'td|j j dSj |j j | }| | }|urdS|dd f| fd }td |j j |S) uRegister a speech-to-text backend. ``provider`` must be an instance of :class:`agent.transcription_provider.TranscriptionProvider`. The ``provider.name`` attribute is what ``stt.provider`` in ``config.yaml`` matches against when routing :func:`tools.transcription_tools.transcribe_audio` calls — **but only when**: 1. ``provider.name`` is NOT a built-in STT provider name (``local``, ``local_command``, ``groq``, ``openai``, ``mistral``, ``xai``). Built-ins always win — the registry rejects shadowing names with a warning. 2. There is NO ``stt.providers.: type: command`` entry with the same name. Command-providers win on name collision because config is more local than plugin install — same precedence rule as TTS. Coexists with the in-tree dispatcher and the STT command-provider registry rather than replacing them. The 6 built-in STT backends keep their native implementations in ``tools/transcription_tools.py``; this hook is for *new* Python engines (OpenRouter, SenseAudio, Gemini-STT, custom proprietary backends). r)TranscriptionProviderr;zrPlugin '%s' tried to register a transcription provider that does not inherit from TranscriptionProvider. Ignoring.Nrtranscription_providerc"|Srr:r>s r1rz?PluginContext.register_transcription_provider.. r@r3rz1Plugin '%s' registered transcription provider: %s)agent.transcription_providerrvagent.transcription_registryrrrrrQrArrrErFrIrr~r+) rr2rv_register_stt_providerrrvrrr?rrs ` @@@r1register_transcription_providerz-PluginContext.register_transcription_provider s6 GFFFFF          ($9::  NNI "    F ++--3355  '((eDDDxu5555**=FFF X % %4(( $ *E=A )     ? M      r3radapter_factoryvalidate_config required_env install_hint entry_kwargsc . ddlmm} |djj| d|||||pg|dd|} jj}  |  d| us ddSjj  d d f | fd fd  } td jj| S)uRegister a gateway platform adapter. The adapter_factory receives a ``PlatformConfig`` and returns a ``BasePlatformAdapter`` subclass instance. ``check_fn`` is a PASSIVE dependency probe — "are deps importable right now?". It must never install anything: status displays and config loading call it freely. If your platform's SDK is lazy-installable, pass the ACTIVE installer separately as ``ensure_deps_fn`` (forwarded via ``entry_kwargs``); the gateway calls it from ``create_adapter()`` when ``check_fn`` is False, right before connecting the platform. Extra keyword arguments are forwarded to ``PlatformEntry`` (e.g. ``setup_fn``, ``emoji``, ``allowed_users_env``, ``platform_hint``, ``ensure_deps_fn``). Unknown keys raise TypeError from the dataclass constructor. Example:: ctx.register_platform( name="irc", label="IRC", adapter_factory=lambda cfg: IRCAdapter(cfg), check_fn=lambda: True, emoji="💬", setup_fn=irc_interactive_setup, ) r)platform_registry PlatformEntry plugin_namer)rrr}rr~rrrrrNrc6|Sr)_restore_platform_registration)rrrrrrs r1rz1PluginContext.register_platform.. s"(K(K!4+u))r3c8jSr)rI _remove_platform_name_if_unownedrsr1rz1PluginContext.register_platform..! sT]KKDQQr3rz!Plugin %s registered platform: %sr:)gateway.platform_registryrrrrrrIrrr_plugin_platform_namesrrr~rQrT)rrrr}rr~rrrrrVrvrrrrs`` @@@r1register_platformzPluginContext.register_platform sR ONNNNNNN t}/ABBB  ++%+%       '$::4u:MM""5"666#99$e9LL 1:U " "gaj&<4 ,00666((  eT*RQQQQ)     / M      r3rc4|||||Srrrrrrrrs r1rz,PluginContext._restore_platform_registration* *!55 ';e6   r3 action_idct|stdjjd|)t |t r1|stdjjd||jjfjj  dt|fd}t djj||S)uRegister a Slack Block Kit action handler from a plugin. Hermes' Slack adapter wires registered handlers into its ``slack_bolt.AsyncApp`` at connect time. The callback is invoked when a user clicks a button (or interacts with another Block Kit action element) whose ``action_id`` matches. Callback signature follows the slack_bolt convention:: async def handler(ack, body, action) -> None: await ack() # required, within 3 seconds ... Args: action_id: Whatever ``slack_bolt.App.action()`` accepts — a literal ``action_id`` string, a compiled ``re.Pattern`` for matching multiple ids, or a constraint dict (e.g. ``{"action_id": "...", "block_id": "..."}``). callback: Async callable receiving ``(ack, body, action)``. Raises: ValueError: if ``callback`` is not callable, or ``action_id`` is empty/None. Example:: async def _on_approve(ack, body, action): await ack() # apply some workflow keyed on action["value"] ctx.register_slack_action_handler("inbox_sweep_approve", _on_approve) Plugin 'zH' tried to register a Slack action handler with a non-callable callback.NzC' tried to register a Slack action handler with an empty action_id.slack_action_handlercNjjjSr)rI_remove_identity_slack_action_handlers)rVrsr1rz=PluginContext.register_slack_action_handler..l s#DM22 4er3z-Plugin %s registered Slack action handler: %s)rr@rrrrrErIrrrsrrQrT)rrrrrVs` @r1register_slack_action_handlerz+PluginContext.register_slack_action_handler8 s,J!! @4=-@@@   Is!;!; IOODUDU ;4=-;;; Hdm&89 ,33E::: " OO         ; M      r3)defaultsrJrc  rttstdjjdt dDs tdjjddddlm}d|D}|vr0tdjjd d jjd d jjp jj}j j }|O| d|kr6tdjjd d| dddddddid} |r| D] \} } | | | < ||| ||dj j <j j  ddtj j f | fd} tdjj|| S)uRegister a plugin-defined auxiliary LLM task. Auxiliary tasks are LLM-backed side jobs (vision analysis, web extraction, compression, smart-approval, etc.) that route through ``auxiliary_client.py``. Each task has its own ``auxiliary.`` config block where users can pin a provider/model independent of the main chat model. Plugins use this to declare their own auxiliary tasks without touching core files. After registration, the task: - Appears in the ``hermes model → Configure auxiliary models`` picker - Has its provider/model/base_url/api_key bridged from config.yaml to ``AUXILIARY__*`` env vars at gateway startup - Gets default routing fields (provider="auto", model="", etc.) merged into loaded configs so ``cfg.get("auxiliary", {}).get(key)`` works Args: key: stable task key (snake_case). Used in config ``auxiliary.`` and env vars ``AUXILIARY__*``. Must not shadow a built-in task key (vision, compression, web_extract, approval, mcp, title_generation, skills_hub, curator). display_name: human-readable name shown in the picker. description: short one-line description shown next to the name. defaults: optional dict of default routing fields. Recognized keys: ``provider`` (default "auto"), ``model`` (default ""), ``base_url`` (default ""), ``api_key`` (default ""), ``timeout`` (default 60), ``extra_body`` (default {}), plus any task-specific extras (e.g. ``download_timeout``). Unknown keys are preserved verbatim — the plugin owns the schema for its own task. Raises: ValueError: if *key* is empty, contains invalid characters, or shadows a built-in auxiliary task key. Example: ctx.register_auxiliary_task( key="memory_retain_filter", display_name="Memory retain filter", description="hindsight pre-retain dedup/extract", defaults={"provider": "auto", "timeout": 30}, ) rz4' tried to register auxiliary task with invalid key c3JK|]}|p|dkVdS)_N)rros r1rz8PluginContext.register_auxiliary_task.. s388q199;;*!s(888888r3z' auxiliary task key z: must contain only alphanumeric characters and underscoresr) _AUX_TASKSch|]\}}}| Sr:r:)rrl_name_descs r1 z8PluginContext.register_auxiliary_task.. sDDDoaDDDr3z!' cannot register auxiliary task uS — that key is reserved for a built-in task. Pick a plugin-namespaced key (e.g. 'rz').Nru# — already registered by plugin ''autor<<)r2rbase_urlapi_keyr extra_body)rrJrrrrauxiliary_taskrcRjjj|Sr)rIr _aux_tasks)rrVrrs r1rz7PluginContext.register_auxiliary_task.. s' (F(F (#uk))r3rz,Plugin %s registered auxiliary task: %s (%s))rrr@rrallhermes_cli.mainrrrIrrrCr~rrQrT)rrrJrr_BUILTIN_AUX_TASKS builtin_keysowner_idexistingmerged_defaultsrlvrrVs`` @r1register_auxiliary_taskz%PluginContext.register_auxiliary_task{ sj *S#.. ,4=-,,$',, 88C88888 M4=-MMCMMM  EDDDDDDD1CDDD ,  U4=-UUUU7;}7IUULOUUU =$: (:=+//44  HLL$:$:h$F$F.4=-....LL**...  + +   ' (( ' '1%&""(&'" ) )   % (-((  #R (@%A%A3G )     : M        r3r0cddlm} ||d|jj}n>#t$r1}t d|jj|Yd}~dSd}~wwxYwt d|jj||S)uAdditively register secret-token regexes with the redaction engine. Accepted patterns join the vendor-prefix alternation in :mod:`agent.redact` and are masked everywhere built-in patterns apply — logs, terminal output, transport errors, transcripts — with the same head/tail masking and the same non-reusable sentinel on ``file_read`` content. Historically every new vendor token format required a core PR appending to ``_PREFIX_PATTERNS``; provider plugins should own their own format instead. The registry is **additive-only**: plugins can extend what gets masked but cannot remove or weaken built-in patterns, so a plugin can only ever over-redact, never expose. The operator's global opt-out (``security.redact_secrets: false``) applies to plugin patterns exactly as it does to built-ins. Each pattern must compile as a regex and start with at least 2 literal characters (e.g. ``r"nvapi-[A-Za-z0-9_-]{20,}"``). Invalid entries are warned and skipped — never raised. Returns the number of patterns accepted. r)register_redaction_patternsrrz5Plugin '%s' redaction pattern registration failed: %sNz,Plugin %s registered %d redaction pattern(s)) agent.redactrrrrrQrArT)rpatternsr4countrs r1rz)PluginContext.register_redaction_patterns s0 JIIIII I!?4=+=!?!?EE    NNG "C   11111    : M     s# A&AA hook_namec tvrLtdjjdt tjj g}|  dfd}t djj|S)zRegister a lifecycle hook callback. Unknown hook names produce a warning but are still stored so forward-compatible plugins don't break. z4Plugin '%s' registered unknown hook '%s' (valid: %s)rhookcPjjjSr)rI_remove_callback_hooks)rrrsr1rz-PluginContext.register_hook..< s%DM22 $ir3zPlugin %s registered hook: %s) r|rQrArrrrDrIrrrrsrT)rrr callbacksrs``` r1 register_hookzPluginContext.register_hook* s K ' ' NN " &--..    M(33IrBB """ I          4dm6H)TTT r3r)rrrrrrc  tstdt|tst |st d|t vr7tddtt zt|ts)t|trd|cxkr tksntdtj j }|tdd |jjjp jj}t'||||  j j <ddl}d d |j j f | fd }t.djj|S)a3Register bounded context that is frozen into each new session prompt. Callables receive a read-only session-info mapping. The rendered full system prompt is already persisted by core and restored verbatim, so no parallel plugin-section state is needed for process restarts. zdsystem prompt section id must be 1-128 lowercase characters using letters, numbers, '.', '_', or '-'z:system prompt section content must be a string or callablez/system prompt section position must be one of: rrz6system prompt section max_chars must be between 1 and Nzsystem prompt section z! is already registered by plugin )rrrrrsystem_prompt_sectionrcRjjj|Sr)rIr_system_prompt_sections)rrsectionrs r1rz>PluginContext.register_system_prompt_section.. s' (F(F 5r7K))r3rz.Plugin %s registered system prompt section: %s)rr@rrrr?SYSTEM_PROMPT_SECTION_POSITIONSrrDrBr0MAX_SYSTEM_PROMPT_SECTION_CHARSrIrrrrrrrbuiltinsr~rrQrT) rrrrrrrXrrrs `` @r1register_system_prompt_sectionz,PluginContext.register_system_prompt_sectionC sF144 ; '3'' Z0A0A ZXYY Y : : :A))F#BCCDDE  y$ ' ' i-- yCCCC$CCCCC5255 =8<:`` where ``plugin_key`` is FORCED to this plugin's own registry key (``manifest.key or manifest.name``). Pass only the bare event name — a plugin may only publish under its own namespace. Passing an already-namespaced name (anything containing ``':'``, including ``hermes:x`` or a foreign ``other:x``) is rejected with a ``ValueError`` and a logged warning — fail-closed. The ``hermes:`` prefix is reserved for core. Delivery is fire-and-forget through a host-owned, single-worker queue: registration order is preserved, while a blocking subscriber cannot stall the emitter. The queue has a bounded pending budget; a full budget drops the new event with a warning. Each subscriber receives a deep-copied payload and is isolated in its own ``try/except``. Awaitable results are resolved through the existing loop-safe plugin path. Returns the count of subscriber callbacks scheduled (0 when there are no subscribers, or when the pending/recursion budget drops the emit). z2Plugin '%s' tried to emit an invalid event name %rrz(' emit() requires a non-empty event nameruPlugin '%s' tried to emit namespaced/reserved event '%s' — a plugin may only emit bare event names under its own '%s:' namespace (the '%s:' prefix is reserved for core, and foreign namespaces are forbidden)z' may not emit 'z>': emit only the bare event name; the namespace is forced to 'z :' and the 'z:' prefix is reserved for coreNz'' emit() payload must be a dict or None) rrrrrrQrAr@HERMES_EVENT_NAMESPACErr?rI_dispatch_event)rrrr full_events r1emitzPluginContext.emit se.]&<$-*<  Juc22  NNDE   O:OOO  %<< NN,E:/E    S:SSuSS@JSS2SSS   z'4'@'@ N:NNN #,,U,, },,ZBGGGr3c"|rt|tstd|jjd|jjp |jj}|j|||t d|jj|dS)uSubscribe *callback* to a fully-qualified event name. *event* is the full ``:`` name (or ``hermes:`` if core ever emits). Subscribing is unrestricted — any plugin may listen to any published event; only *emitting* is namespace-gated. Callbacks are stored in registration order as host-owned ledger entries. The owner key lets plugin unload/reload remove subscriptions before any later event can invoke a zombie callback. rz-' subscribe() requires a non-empty event namez!Plugin %s subscribed to event: %sN) rrr@rrrrI_subscribe_eventrQrT)rrrrs r1 subscribezPluginContext.subscribe s Juc22 (4=-((( ]&<$-*<  &&z5(CCC /1CU     r3c tvrLtdjjdt tjj g}|  dfd}t djj|S)aSRegister a behavior-changing middleware callback. Middleware is separate from observer hooks: request middleware may rewrite the effective payload, and execution middleware may wrap the real callback. Unknown kinds are stored for forward compatibility but warned so plugin authors can catch typos. z:Plugin '%s' registered unknown middleware '%s' (valid: %s)r middlewarecPjjjSr)rIr _middleware)rrrsr1rz3PluginContext.register_middleware.. s%DM22 )4r3z#Plugin %s registered middleware: %s) rrQrArrrrDrIrrrrsrT)rrrrrs``` r1register_middlewarez!PluginContext.register_middleware s ' ' ' NN " &!12233    M-88rBB """ $          :DM:'`` via ``skill_view()``. It does **not** enter the flat ``~/.hermes/skills/`` tree and is **not** listed in the system prompt's ```` index — plugin skills are opt-in explicit loads only. Raises: ValueError: if *name* contains ``':'`` or invalid characters. FileNotFoundError: if *path* does not exist. r) _NAMESPACE_RErz Skill name 'zG' must not contain ':' (the namespace is derived from the plugin name 'z' automatically).zInvalid skill name 'z'. Must match [a-zA-Z0-9_-]+.zSKILL.md not found at zPlugin skill 'z' is already registered)rrr bare_namerrskillrcRjjj|Sr)rIr_plugin_skills)rrV qualifiedrs r1rz.PluginContext.register_skill..2 s' (F(F ,i ))r3rzPlugin %s registered skill: %s)agent.skill_utilsrr@rrmatchexistsr2rrrIrrrrr~rrQrT) rrrrrr namespacervrrVrs ` @@r1register_skillzPluginContext.register_skill s ( 433333 $;;:t::M&:::   =..t44 JtJJJ {{}} E#$CT$C$CDD DM1GT]5G  ))4)) = ! Ri4=3O&O&OPiPPPQQ Q=/33I>>-+At}/A& 1r22   38 $Y/((  #R (D%E%EyQ )     , M      r3)rrrFrGr'r)rXrr'rBrrArB)r'r )rrrrrrr'r)rrrrrurrr rvr rwrxrtryr'r)r'r )rrr'r)rrfr'r)rrrr r'rC)NNFr<r<F)rrrrrPrrUr rrr"rrrBrrrrrrBr'r)rrr'rB)Nr) rrrrrrrr2r'r8)rr r'r8)rXrr'rZ)rrr'rB)r)rrrrrrr'rBr)Nr<) rrr rr r r rrrr'r)r<r<) rrrUr rrrrr'r)rrrrr'r)r'rr)NNr<)rrrrr}r rr r~rrrrrrr r'rrrrrr'rB)rr rr r'r) rrrJrrrrrr'rr@)rrrr r'r) rrrrrrrr0r'r)rrrrr'r0)rrrr r'rC)rrrr r'r)r<N) rrrr rrrrr'r):r6r7r8r9r#rrXrRrXrjrlrprsr~rrrrrrrrrrr classmethodrrCrrrrrrr!r,r5rrCrLrTr\rdrlrtr|rrrrrr'DEFAULT_SYSTEM_PROMPT_SECTION_MAX_CHARSrrrrrr:r3r1rErEqsGG++++777X7     LLLLL86666pX &&X&     (26555555.X (((X(&X*    9=2!!!!J%)$(YYYYYz@@@@,/3 H'H'H'H'H'T![4111\1(RRRRHD #' DDDDDDL    , '+ #####N  BBBBBL    B((((X     H    @,,,,`8888x,,,,`----b1111j>>>>D7777v====B,0$(MMMMM^     ====F.2 @@@@@@H((((T<'@ KKKKKK^2H2H2H2H2Hh    0: 37 >>>>>>>r3rEceZdZdZdddZddZeddZddZdd Z dd"Z dd$Z dd%Z dd(Z dd)Zedd,Z ddd.Z ddd/Zedd0Zdd5Zdd6Zdd8Zddd;Zdd<Zdd=Zdd>ZddAZddBZddDZddGZ dddMZddQZ ddUZ!ddVZ"ddWZ#ddXZ$e%ddYZ&dd\Z'dd]Z(dd^Z)dd`Z*ddaZ+ddbZ,ddcZ-dddZ.ddeZ/ddfddiZ0ddjZ1eddlZ2ddoZ3ddqZ4ddrZ5ddsZ6ddtZ7ddwZ8ddyZ9dd|Z:dddZ;ddZddZ?ddZ@ddZAddZBddZCddZDddZEddZFddZGddZHddZIdS) PluginManagerz;Central manager that discovers, loads, and invokes plugins.Nrrfr'rCc|p t|_t|j|_t j|_i|_i|_i|_ t|_ t|_ i|_ d|_i|_i|_d|_d|_d|_i|_i|_i|_i|_i|_t j|_t j|j|_d|_ddi|_t=jt@|_!d|_"t j#|_$g|_%i|_&g|_'i|_(i|_)dS)NFrmaxsize)*rrr rrr_discovery_lockrPrrrrrrr&rr _discoveredr_gateway_message_injectorr_portable_mcp_serversrr_subscriptions _event_lock Condition _event_idle_event_generation_event_pending_by_generationqueueQueue_EVENT_PENDING_CAP _event_queue _event_workerlocal _emit_depthr_ownership_ledger_registration_order_predeclared_modules_predeclared_tools)rrs r1r#zPluginManager.__init__D ss#7o&7&7dn--(0013 13 68,/EE03#.0#13MO$!& IM&9;@B"6846!DF$?,,$.t/?@@!"=>F).3k&/ / / :>%?,,46# GI=? BD!8:r3rrrrrrrrc|jp|j}t||||}fd|_j|g|j||S)zBRecord one successful registration under its canonical plugin key.)rrrrc0|gSr)_forget_registrations)disposedrs r1rz3PluginManager._track_registration.. sD4N4N J5 5 r3)rrrrrrrr)rrrrrr registrations` r1rrz!PluginManager._track_registration s\2X] )!    $ $ $ $   ))*b99@@NNN  '' 555r3valuesrtargetr rBcntt|dz ddD]}|||ur||=dSdS)z. s\     )!V+ ) D(      r3)rrrdiscardrrs `r1rz*PluginManager._remove_tool_name_if_unowned si    !% 8       2  # + +D 1 1 1 1 1  2 2r3ctfd|jDs|jdSdS)Nc3RK|]!}|jo|jdko |jkV"dS)rNrrs r1rzAPluginManager._remove_platform_name_if_unowned.. s\     )!Z/ ) D(      r3)rrrrrs `r1rz.PluginManager._remove_platform_name_if_unowned si    !% 8       6  ' / / 5 5 5 5 5  6 6r3 registrationsList[PluginRegistration]c|sdSd|Dfd|jD|_t|jD];\}}fd|D}|r ||j|< |j|d. s OOOB|,,OOOr3c6g|]}t|v|Sr:r$rrregistration_idss r1rz7PluginManager._forget_registrations.. s7$ $ $ ,'777 777r3c6g|]}t|v|Sr:r$r's r1rz7PluginManager._forget_registrations.. s7 l##+;;;;;;r3)rrrrCr)rr rowned remainingr(s @r1rz#PluginManager._forget_registrations s  FOOOOO$ $ $ $ $ 8$ $ $  "&d&<&B&B&D&D!E!E = = J$)I  =5>&z22&**:t<<<< = =r3c t|D]\} |#t$r8}td|j|j|tYd}~Ud}~wwxYwdS)z@Dispose registrations in reverse acquisition order, best effort.z.Failed to unload plugin registration %s/%s: %srN)rrrrQrArrrG)rr rrs r1_dispose_registrationsz$PluginManager._dispose_registrationss %]33  L $$&&&&   D + $+    s( A*.A%%A*r(Union[str, PluginManifest, LoadedPlugin]ct|tr|jjp |jjSt|t r|jp|jSt |Sr)rrrrrrrrs r1_resolve_plugin_keyz!PluginManager._resolve_plugin_keysX fl + + ??&>&/*> > fn - - -:, ,6{{r3.Union[str, PluginManifest, LoadedPlugin, None]c|j5t|j5||cdddcdddS#1swxYwYddddS#1swxYwYdS)z@Unload registrations while excluding discovery/deferred loading.N)rrr_unload_scoped)rrs r1unloadzPluginManager.unloads  ! / /#5dn#E#E / /&&v.. / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / /s3A#A  A# A A#A A##A'*A'c |du}|r>t|jt|jzt|j}n|||jvs |jvrhn t}|r|nKfd|jDfd|jDfd|jD}tp|}| || ||rddl m }t|jD]}||d|D t fd|jD}|r dd lm} |D]K} | | #t($r&} t*d | | Yd} ~ Dd} ~ wwxYwn2#t($r%} t*d | Yd} ~ nd} ~ wwxYw|j|j|j|j|j|j|j|j|j|j|j|j|j |j!|j"|j#d|_$d |_%n D]} |j&| d|S) aUnload one plugin or all plugins owned by this manager. Every registration made through :class:`PluginContext` is disposed in reverse acquisition order. Registry inverses are conditional on the exact object still being current, so a later registration is never removed accidentally. ``plugin=None`` is the lifecycle operation used by force rediscovery. ``on_unload`` callbacks and supervised background tasks registered through :class:`PluginContext` are disposed through the same reverse-order ledger walk. Returns ``True`` when at least one plugin or registration was found. Nc:h|]\}}|jjk|Sr:)rr)rrrQ requesteds r1rz/PluginManager._unload_scoped..Cs7#V+y88888r3c3(K|] }|k|V dSrr:)rrr8s r1rz/PluginManager._unload_scoped..Hs:##i''''''##r3c&g|] }|jv |Sr:r)rr target_keyss r1rz0PluginManager._unload_scoped..Ms1 *k99999r3rrc2h|]}|jdk |jSrrrr%s r1rz/PluginManager._unload_scoped..ns3!!! $.. ...r3c3$K|] }|v|V dSrr:)rrledger_tool_namess r1rz/PluginManager._unload_scoped..ss;$$0000000$$r3rz%unload: tool deregister %s failed: %sz&unload: tools.registry unavailable: %sF)'rrrPrrr1rCupdaterBr-rrrrr unregisterrrr deregisterrrQrTclearrrrrrrrrrrrrr&rr)rr unload_allr exactfoundr platform_namepreledger_tools tool_registryrrrrBr8r<s @@@r1r4zPluginManager._unload_scoped's t^  d455DM8J8JJK !9::MM0088Id444 T]8R8RX[X]X]  # '+}':':'<'< ""#####5### $($<M [1M22 ##M222 ""=111 D - D C C C C C!&t'B!C!C < < !,,];;;;!!$1!!!  $$$$$ 3$$$O   HHHHHH&5 )44Y????("LL G ) #!PPPLL!I3OOOOOOOOP  " ( ( * * * M   ! ! ! K        " " $ $ $  # ) ) + + +  ' - - / / /   $ $ & & &  ! ' ' ) ) )   % % ' ' '  & , , . . . O ! ! # # #  ( . . 0 0 0  % + + - - -  ' - - / / /  % + + - - -  # ) ) + + +#'D $D  " - - !!#t,,,, s0G F## G-GG H!HHc|jduS)z@Return whether a live gateway can accept plugin-triggered turns.Nrrs r1rz*PluginManager.has_gateway_message_injectors-T99r3rrinjectorCallable[..., bool]c||f|_dS)z8Publish a live gateway injector and its lifecycle owner.NrN)rrrOs r1set_gateway_message_injectorz*PluginManager.set_gateway_message_injectors +0):&&&r3cB|j}||d|ur d|_dSdSdS)z;Clear the injector only when it still belongs to ``owner``.NrrN)rrrs r1clear_gateway_message_injectorz,PluginManager.clear_gateway_message_injectors:3  !jmu&<&<-1D * * * " !&<&>>@ ==???    #(  ?! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! sdD  D D AD D D'>C&%D&C99D< D D D D D  D$'D$c ddlm}|dS#t$r&}td|Yd}~dSd}~wwxYw)zCRestore config.yaml shell hooks wiped by force-clear of ``_hooks``.r)re_register_config_hooksz/force-reload shell-hook re-register skipped: %sN)agent.shell_hooksr^rrQrT)rr^rs r1rZz2PluginManager._re_register_shell_hooks_after_forcesy Q B B B B B B $ $ & & & & & Q Q Q LLJC P P P P P P P P P Qs A?Ac ddlm}ddlm}m}n#t $rYdSwxYw |}n#t $rYdSwxYw|sdS ddlm}|pi}|dpi}n#t $ri}YnwxYwg}|D]|} t| dd} || } t| tr| ni} | | r| | m#t $rYywxYw|sdS ||td d t#|dS#t $r&} td | Yd} ~ dSd} ~ wwxYw) uIf any plugin secret source is enabled, reset cache and re-apply. Enablement is delegated to each source's ``is_enabled(cfg)`` — the same contract the orchestrator uses (``registry._ordered_enabled_sources``) — so a source with custom activation logic is honored, not just ``secrets..enabled``. No-op when only bundled sources exist or none are enabled. Fail-open: never raise into discover_and_load. r)list_plugin_sources)load_hermes_dotenvreset_secret_source_cacheNrsecretsrr<z8Re-applied secret sources after plugin discovery for: %srz1secret source re-apply after discovery failed: %s)rkrahermes_cli.env_loaderrbrcrrrrrrr is_enabledrrQrTrrD) rrarbrcplugin_sourcesrrrd enabled_namesrrrrs r1rYz5PluginManager._refresh_secret_sources_after_discoverysV  I I I I I I [ [ [ [ [ [ [ [ [    FF  0022NN    FF   F  5 5 5 5 5 5+--%2Cggi((.BGG   GGG  $  F662..Dkk$''G!+GT!:!:BggG $$W--/!((...      F S % % ' ' '   LLJ &//00      S S S LLLc R R R R R R R R R SsU  . <<)A.. A=<A=*C11 C>=C>AE F!FFc |}|}tdt |||t }t}t|}|r4t dd |ti}|D]}|||j p|j <i}|D]}|j p|j } | tvs|j tvrMt!|d} dtd| _| |j| <t d| | ju| |vs |j |vr>t!|d} d | _| |j| <td | |jd kr?t!|d} d | _| |j| <td |  |jdkr8t!|d} | |j| <td| M|jdkr"|jdkr||z|jdkr"|jdkr|||duo | |vp|j |v} | sRt!|d} d| | _| |j| <td|  ||| <t1|D]I} || }||||||J|r^tdt |jt9d|jDdSdS)u=The actual discovery sweep — see :meth:`discover_and_load`.z entrypoints: %d manifest(s)zqRemoved Hermes plugin %s is still listed in plugins.enabled; remove it and configure native Relay plugins with %srFrru?removed — Relay lifecycle is owned by Hermes core; configure z insteadz5Refusing to load removed Hermes Relay plugin '%s'; %szdisabled via configzSkipping disabled plugin '%s'ru<exclusive plugin — activate via .provider configz8Skipping '%s' (exclusive, handled by category discovery)rTz?Skipping '%s' (model-provider, handled by providers/ discovery)rrrNzBnot enabled in config (run `hermes plugins enable {}` to activate)z&Skipping '%s' (not in plugins.enabled)z/Plugin discovery complete: %d found, %d enabledc3(K|] }|j dVdS)rN)rrs r1rz9PluginManager._discover_and_load_inner..s)CC!CACCCCCCr3)_collect_directory_manifests_scan_entry_pointsrQrTrrxrrr&rArr%rrr r$rrrPrr _load_plugin_register_deferred_platformformatr_warn_python_dependencies_validate_plugin_config_schemar+sum) rr ep_manifestsrrstale_relay_keyswinnersrto_load lookup_keyrQrfs r1rXz&PluginManager._discover_and_load_inner(sV*.*K*K*M*M ..00  4c,6G6GHHH&&&)**&((3G<<   NNG *++(     .0! > >H5=GHL1HM 2 2.0((h +h +H!6J 666=$<<<%xGGG:/::: -3 j)KL X%%()B)B%xGGG4 ,2 j) Register one plugin-owned approval transport for this profile.rN)RegisteredApprovalTransportbuiltinz-approval transport name 'builtin' is reservedz[a-z0-9][a-z0-9_-]{0,63}z;approval transport name must match [a-z0-9][a-z0-9_-]{0,63}z.approval transport present_fn must be callablezapproval transport z is already registered by )rr_rX profile_homez+Plugin %s registered approval transport: %s)rhermes_cli.approval_transportrzrrErFr@rrr?rrXrr.rQr+)rrrrXrrzrrs r1rz)PluginManager.register_approval_transportsR  MMMMMMD !!'')) I  LMM Mr|7?? M  ## NLMM M D- - --e4>EReRRRR ,G+F_..668899 , , , !%(  A9eTTTTTr3c|jt|}|dS|jtt krdS|S)z>Return a transport only inside the profile that registered it.N)rrrrErFr|rr.)rrrs r1get_approval_transportz$PluginManager.get_approval_transportsr.223t99??3D3D3J3J3L3LMM  4  "c/*;*;*C*C*E*E&F&F F F4r3List[PluginManifest]cg}t}td|||dhd}tdt |||||dz d}tdt |||t d z }td |||d }td t |||td rtj dz d z }td|||d}tdt |||ntd|S)aCollect directory manifests in the same order as full discovery. This method only reads manifests. It does not load native plugin modules, register deferred platforms, or otherwise mutate manager registries. Keeping the source ordering and scanner calls here lets startup probes share the exact precedence and containment rules used by :meth:`_discover_and_load_inner`. zScanning bundled plugins: %sr>model-providersmemoryrr$)r skip_namesz% bundled (top-level): %d manifest(s)rrz# bundled/platforms: %d manifest(s)r*zScanning user plugins: %srz user: %d manifest(s)HERMES_ENABLE_PROJECT_PLUGINSz.hermeszScanning project plugins: %sprojectz project: %d manifest(s)zHProject plugins disabled (set HERMES_ENABLE_PROJECT_PLUGINS=1 to enable)) r2rQrT_scan_directoryrrxrrr cwd) rr repo_pluginsrbundled_platformsuser_diruser_manifests project_dirproject_manifestss r1rlz*PluginManager._collect_directory_manifestss+- /00  3\BBB&& SSS'    /B/BCCC((( 7 8 8 (**y09.4s'NNNUz%7M7MN5NNNr3rc<h|]}t|t|Sr:rrs r1rz9PluginManager.has_enabled_portable_mcp..7s' I I Iu*UC2H2H IU I I Ir3r) _discover_mcpr%) create_dataT)rrrrrrrlrrr rhermes_cli.agent_pluginsrr rrrr3r4r@) rrplugins_config enabled_valuerdisabled_valuerrvrrxrs r1has_enabled_portable_mcpz&PluginManager.has_enabled_portable_mcp$s * + + 5# 22.$// 5&**955 -.. 5NNmNNN'++J;;.$//  I I I I I I   5-/99;; > >H5=GHL1HM 2 2((  H$ !6JX%%()B)B((X]'-I-I BBBBBB =''#%%#$/=:? %   44 \:6    us2AE66FFrr rrOptional[Set[str]]c6||||ddS)uRead ``plugin.yaml`` manifests from subdirectories of *path*. Supports two layouts, mixed freely: * **Flat** — ``//plugin.yaml``. Key is ```` (e.g. ``disk-cleanup``). * **Category** — ``///plugin.yaml``, where the ```` directory itself has no ``plugin.yaml``. Key is ``/`` (e.g. ``image_gen/openai``). Depth is capped at two segments. *skip_names* is an optional allow-list of names to ignore at the top level (kept for back-compat; the current call sites no longer pass it now that categories are first-class). r<rrr1r)_scan_directory_level)rrrrs r1rzPluginManager._scan_directory`s,*)) &Z!*   r3r1rr0cg}|s|St|D]=}|s|dkr |r |j|vr*|dz }|s|dz }|r0|||||} | || |dz } | s| r ddlm } | |\} } | D]#}t d||j $|r |d|jn| d }|t| d | d d | d d t| d d |t!||dt#| n3#t$$r&}t d| |Yd}~nd}~wwxYw|dkrtd||r |d|jn|j}||||d||dz?|S)aRecursive implementation of :meth:`_scan_directory`. ``prefix`` is the category path already accumulated ("" at root, "image_gen" one level in). ``depth`` is the recursion depth; we cap at 2 so ``/a/b/c/`` is ignored. rz plugin.yamlz plugin.ymlNz plugin.json)read_agent_plugin_manifestzAgent Plugin '%s': %srrrr<rrT) rrrrrrrrrFailed to parse %s: %srz/Skipping %s (no plugin.yaml, depth cap reached)r)is_dirrDiterdirrr_parse_manifestr is_symlinkrrrQrAmessagerrrrrrrTrxr)rrrrr1rrchild manifest_filer portable_filerr7 diagnostics diagnosticrr sub_prefixs r1rz#PluginManager._scan_directory_levelys+- {{}}  DLLNN++? ? E<<>> zzjzUZ:-E-E!M1M '')) 5 % 4 ##%% //!5&&'$$X...!M1M##%% )A)A)C)C QSSSSSS(B(B5(I(I%D+&1 3!&. 7=NV22ej222$v,C$$&!%f$(HHY$;$;(,(C(C#2488Hb3I3I#J#J#)!$U #%),Ec,J,J       !QQQNN#;]CPPPPPPPPQ zz NPUVVV5;KF11UZ111J   **#%!) +    s5C$G H $HH r plugin_dirOptional[PluginManifest]c ttd|dSt|dpi}|d|j}|r |d|jn|}|dd}t|tsd}| } | tvrDtd ||d ttd} | dkr|d|vrx|d z } | r_ t| d d dd} | r| } td|| | n#t"$rYnwxYwtd||| ||t%||} t'd|t|dd|ddt)|dd|dg|dg|dg|t|| |t+|d|d | |dpg|dpgdS#t"$r.} td|| t,Yd} ~ dSd} ~ wwxYw) zParse a single ``plugin.yaml`` into a :class:`PluginManifest`. Returns ``None`` on parse failure (logs a warning). Nu'PyYAML not installed – cannot load %srr/rrrrzBPlugin %s: unknown kind '%s' (valid: %s); treating as 'standalone'rrr)rrrz-Plugin %s: detected %s, treating as kind='%s'z9Parsed manifest: key=%s name=%s kind=%s source=%s path=%srr<rrr"r%r$r) rrrrr"r%r$rrrrrrr)rrrrr:)yamlrQrArrrrrrrErFrrrDrrrTrrWrrrrG)rrrrr1r7rrraw_kindr init_filedetected v2_fieldsrs r1rzPluginManager._parse_manifestseI |H-XXXt!-"9"97"9"K"KLLRPRD88FJO44D39CV//jo///tCxx 55Hh,, ('>>##))++D...X499V4G-H-H#I#I$|##d(:(:&6 ##%% #;%//'070#te%$$ $#+D"LL O #Xx% LLKT4   2$< onnxruntime), and logged ``no register() function``. Classification removes the cost without changing the activation surface, and is the prerequisite that prevents double-import once entry-point activation lands. rrrr)rrrErrr)rrrrs r1_classify_entrypoint_kindz'PluginManager._classify_entrypoint_kind)s|> (..a00399;;K $#|0==K+K88HL H   << s5AA A'&A'ctS)a8Read installed plugin and companion capability entry points. Delegates to ``discover_entrypoint_manifests()``, which composes kind classification (import-free source scan routing memory/model providers away from the general manager) with capability declarations from the ``hermes_agent.plugin_capabilities`` group. Capability declarations live in distribution metadata so discovery is available before importing untrusted plugin code and does not depend on a package-data ``plugin.yaml`` being present. )rrs r1rmz PluginManager._scan_entry_pointsQs-...r3c|jpd}|dr|dtd S|jrt |jjS|S)aDerive the gateway platform name (e.g. ``feishu``) for a platform plugin. The platform name registered via ``register_platform(name=...)`` lives inside the adapter module (which we are explicitly trying NOT to import early). It is not carried in ``plugin.yaml``. Across every bundled platform plugin the manifest name is ``-platform`` and the plugin directory basename is ````, so we derive the name without importing: strip a trailing ``-platform`` from the manifest name, falling back to the directory basename. This is also a sensible convention for third-party platform plugins. r<z -platformN)rrrrr )rrrs r1_platform_name_from_manifestz*PluginManager._platform_name_from_manifestbsb}" == % % -+3{++++, , = , &&+ + r3c $ |jp|j}|t|d}d|_|j|< ddlm j |fd fd }  } |   dhd |ur^j tjd f| fdfd}|d |jt"d|nC#t&$r6t"d|d|Yd SwxYw||d S)aRegister a lazy loader for a bundled platform plugin. The platform adapter module is imported only when the gateway / cron / setup / send_message path first asks the ``platform_registry`` for this platform. Until then we record a lightweight ``LoadedPlugin`` so ``hermes plugins list`` still shows the platform as available, and we hand the registry a loader that runs the normal eager-load path. Trjrr= _manifestrr'rCc*j5tj5r dddddddS|dddn #1swxYwYddddS#1swxYwYdSr)rrris_deferred_load_cancelled_load_plugin_scoped)rrJrrrs r1_loaderz:PluginManager._register_deferred_platform.._loaders[ )88+=dn+M+M88(CC%UD 88888888888888 ,,Y777 888888888888888888888888888888888s?BA0 BA0$ B0A4 4B7A4 8BB B rNrrc6|Sr)_restore_deferred_platform)rrrJrrrs r1rz;PluginManager._register_deferred_platform..s&0O0O)%# 11r3c.Sr)r)rJrsr1rz;PluginManager._register_deferred_platform..sT%J%J%&&r3r{z3Registered deferred platform loader: %s (plugin=%s)z=Deferred platform registration failed for '%s'; eager-loadingr)rrr'rC)rrrrrrPrrrrregister_deferredrrrrr|rrrrQrTrrn!_register_deferred_platform_tools) rrrxrQrrvr}rrJrrs ` @@@@r1roz)PluginManager._register_deferred_platformusr\2X] 99(CC x>>>$* j!@  C C C C C CNE4< 8 8 8 8 8 8 8 8 8 8)>>U?H  / /we 0   (==U>Gqz!gajG&;&;+// >>>/7 6#%((!M  LLE         LLO       h ' ' ' FF  ..x@@@@@s C*D77/tools.py`` does not import the adapter, so the SDK stays unloaded and startup stays cheap. A plugin taking this path must therefore keep its package ``__init__`` import-light and pull the adapter in from inside ``register()`` (as ``plugins/platforms/a2a`` does). Opting in is explicit: the manifest must declare ``provides_tools`` (the field the plugin list and web server already read to name a plugin's tools, per #78538). Keying off the mere presence of a ``tools.py`` would opt a plugin in by accident — a platform is free to put internal helpers there — and would leave the contract invisible to anyone reading the manifest. ``tools.py`` remains where the code is imported from; ``provides_tools`` is what asks for it. A platform that does not declare the field is untouched and stays fully deferred. Nztools.pyzrPlugin '%s' declares provides_tools %s but has no tools.py; those tools will not be available in CLI/TUI sessions.z.toolsregister_toolszPlugin '%s' declares provides_tools %s but its tools.py has no register_tools(ctx); those tools will not be available in CLI/TUI sessions.cg|]}|v| Sr:r:rr>befores r1rzCPluginManager._register_deferred_platform_tools..s%avooooor3z;Deferred platform '%s': pre-registered %d client tool(s) %scg|]}|v| Sr:r:rs r1rzCPluginManager._register_deferred_platform_tools..'sMMMQQf__q___r3zbefore registering any of its z declared tool(s)zafter registering all zafter registering z of z;Plugin '%s': client-tool pre-registration failed %s (%s).%sr<z5 The remainder will be missing from CLI/TUI sessions.r)r%rrrr rrQrArrr_load_directory_modulerrr import_moduler6rrErrrTrrrG)rrrQrxrr tools_modulerrrrhdeclaredrrs @r1rz/PluginManager._register_deferred_platform_toolss>&  F\2X] ,4MCT(-(((t  j:&=%F%F%H%H  NNIX,--     FT,--E 00::F#FM4:D %j 1$2fo3M3M3MNNL$\3CTJJN%5011  N=488 9 9 92J'1F #2*1'6=' 38233H [TTTTW))LLLLZS\\ZZxZZZ NNM'llh..G'          9$ s!BFA'F I B-H??Ic ^|j}|sdS|jp|j}g}|D]}tjd|dd}|s4 t j|U#t jj $r| |Yt$rYwxYw|rOt d|d|dd |DdStd |d|dS) uSurface declared pip dependencies (#64165). python_dependencies is a declaration seam ONLY: Hermes validates and prints the requirements with an install hint but NEVER auto-installs them. The isolation design (constraints installs vs. vendored dirs vs. conflict-detection-and-refusal) is an explicitly deferred follow-up — see the round-2 review on #64165 and #15220. Nz [<>=!~\[;\s]r)maxsplitrzPlugin %s declares Python dependencies that are not installed: %s. Hermes does not install plugin dependencies automatically; install them yourself, e.g.: pip install %srrc3"K|] }d|dV dS)rNr:)rms r1rz:PluginManager._warn_python_dependencies..fs*33aQ333333r3z+Plugin %s python_dependencies satisfied: %s)r)rrrrrErrrPackageNotFoundErrorrrrQrArrT)rrrJrrWreqrs r1rqz'PluginManager._warn_python_dependenciesGso+  Fl+hm  C8OS1===a@FFHHD  "**40000%: $ $ $s#####       NNMTYYw''33733333       LL=TYYt__     sA33)B* B*)B*c|jsdS|jp|j}i} ddlm}|pi}|dpidpi}t |tr||nd}t |tr|dnd}t |ts,t |tr|dnd}t |tr|ni}n#t$ri}YnwxYwt||j|D]} t d|| dS) zCheck plugins.entries. settings against config_schema (#64165). Mismatches log actionable warnings naming the key and expected type; they never block the plugin from loading. Nrrr*rUrYrzPlugin %s config: %s) r#rrrrrrrrrbrQrA) rrrXrYrrrUrVrrAs r1rrz,PluginManager._validate_plugin_config_schemans %  FL1HM &(  5 5 5 5 5 5+--%2Cwwy))/R44Y??E2G.8'.J.JTGKK ***PTE+5eW+E+EO%))J'''4Cc7++ R-7w-G-GQeii)))T(g66>ssBHH   HHH - x-x   G GG NN19g F F F F G GsC0D DDrc4|||||Srrrs r1rz(PluginManager._restore_deferred_platformrr3c|j5t|j5||dddn #1swxYwYddddS#1swxYwYdS)z?Import a plugin module and call its ``register(ctx)`` function.N)rrrr)rrs r1rnzPluginManager._load_plugins  ! / /#5dn#E#E / /  $ $X . . . / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / / /s1A? AA AA AAAc D t|}td|jp|j|j|j|j|jr ||dSddl m tj }|jp|j| tj5 j} t)|djtjdj f| fd  }|d |jdddn #1swxYwY jd}||}n6|jd vr| }n|}||_t=|d d}|)d|_t d|jn3t)|} || fdj |dDfdj!gD fdDz|_"dD|_#dD|_$dD|_%d|_&tdt|j"t|j#t|j$t|j%tOfdj(Dn#tR$r} fdj D} *| +| tY| |_-t d|j| t\Yd} ~ nd} ~ wwxYw|j&sj!d|j/|jp|j<dS)z9Load one plugin with the manager's home bound as current.)rz1Loading plugin '%s' (source=%s, kind=%s, path=%s)Nrrrr<tool_override_policyc@|jSr)restore_plugin_override_policyr)r _module_name _registrycurrent_policyrs r1rz3PluginManager._load_plugin_scoped..s+I,T,T ". -U--r3)rrvrw>rrrrrzno register() functionz&Plugin '%s' has no register() functionc8g|]}|jk |j|Sr:)rrrrrs r1rz5PluginManager._load_plugin_scoped..s9!!!$#.*<<AT<!<<rs r1rz5PluginManager._load_plugin_scoped..s1   D333333r3cFg|]}|jdkr|jv|jSr?r@)rr _predeclareds r1rz5PluginManager._load_plugin_scoped..sD:::$#(F22$( <<!$=<.s3+++$#(F22!$222r3c2g|]}|jdk |jS)rr@r%s r1rz5PluginManager._load_plugin_scoped..s3000$#(L88!$888r3c2g|]}|jdk |jS)rr@r%s r1rz5PluginManager._load_plugin_scoped..s3...$#(I55!$555r3Tz[ registered: %d tool(s), %d hook(s), %d middleware, %d slash command(s), %d CLI command(s)c3VK|]"tfdDdV#dS)c3hK|],}|jo |jko|jdko |jkV-dS)rN)rrrr)rrrprs r1rz>PluginManager._load_plugin_scoped... sn !- )/6 , 7: E6 , 1] B6!- 0A 5 r3rN)r)rrprr s @r1rz4PluginManager._load_plugin_scoped..su   1>        r3c*g|]}|jk |Sr:r;rs r1rz5PluginManager._load_plugin_scoped..s1 *j88888r3zFailed to load plugin '%s': %sr)0rrQrTrrrrrr_load_portable_pluginrrrr_policy_module_namerrsnapshot_plugin_override_policyrregister_plugin_override_policyrErr|rrrrrr_load_entrypoint_modulerrrrArrrrrrrsrrr-rr_remove_plugin_subscriptionsrGrP)rrrQregistration_startprevious_policy policy_lease preloadedr register_fnctxrr*rrrrrr s` @@@@@@r1rz!PluginManager._load_plugin_scopeds}x000 ? L )HM8?HM8=       & &x 8 8 8 F888888 !9::\2X] //99 $ 0 2 2  'GGDNHO'FFh--DDRHHnGN 3:'F&(   L  $ $&$    )               4^ 155j$GGI$"$BBB44,555h??"FM"&*d;;K"7 GWWWW#Hd33 C   !!!!(,(@ASATAT(U!!!     #6:::rJJ    +7::::(5:::+' ++(5+++' 00(5000, ..(5...* "& q/00/00455233     #'#5      $   $($<E  ' ' . . .  & &u - - -s88FL  - -j 9 9 9 NN0 s^          2~ :  # ' ' D 9 9 97= hl3hm444s-BE**E.1E.6G M O% BO  O%c~|jp|j} ddlm}|t |jt dz |jz }t||}|j D])}t d||j |j *|jD]h} ||j|j|j|j0#t&$r,} t d||j| Yd} ~ ad} ~ wwxYw|jD]N\} } |jd| } | |jvrt d|| 7t/| |j| <Od |_nG#t&$r:} t3| |_t d || Yd} ~ nd} ~ wwxYw||j|<dS) zALoad validated portable components without importing Python code.r)load_agent_pluginr%zAgent Plugin '%s' [%s]: %sz(Agent Plugin '%s' skill '%s' skipped: %sN__z*Agent Plugin '%s' MCP server collision: %sTz$Failed to load Agent Plugin '%s': %s)rrrrr rrrrErrQrArrskillsrskill_mdrrr mcp_serversrCrrrrrrP) rrrQrxrpackagerrrr server_namer internal_names r1rz#PluginManager._load_portable_plugin0sP \2X] + T B B B B B B''X]##!!M1H4LLG $//C%1   0$&  !   && ))  !NNB"  (/':'@'@'B'B I I# V#+#; L L{ L L  D$>>>NND"% <@LL*=99!FNN T T Ts88FL NNA:s S S S S S S S S T%+ j!!!sCBE,,CE, C9 "C4/E,4C99A2E,, F060F++F0c |jp|j}|dddd}td|}t5t |}||jt |<|cdddS||jkr|cdddStj |j d dd}|d |cdddS#1swxYwYdS) z>Return a profile-safe import namespace for a directory plugin.rrrrrNr __home_) rrr _NS_PARENT_MODULE_NAMESPACE_LOCKrrrrr r r )rrrr rrr s r1_directory_module_namez$PluginManager._directory_module_namedsl+hm{{3%%--c377!**D** # 1 1&**955E}04"9-  1 1 1 1 1 1 1 1 &&  1 1 1 1 1 1 1 1^DN$9$9'$B$BCCMMOOPSQSPSTF0000 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1s -C8 C8A C88C<?C<c|jdkrJ|jrCt|jdd}|r|S||S)z?Return the module prefix whose callbacks inherit plugin policy.rrr)rrr partitionrEr)rrrs r1rz!PluginManager._policy_module_namessf ?l * *x} *hm,,66s;;A>DDFFK #""**8444r3rrtypes.ModuleTypec t|j}|dz }|std|tt jvr@tjt}g|_ t|_ |t jt<p| |d  fdt jDD]}t j|=tj |t|g}||jt#d|tj |}|_ t|g|_ |t j< |j|n8#t($r+ fdt jDD]}t j|=wxYw|S) a/Import a directory-based plugin as ``hermes_plugins.``. The module slug is derived from ``manifest.key`` so category-namespaced plugins (``image_gen/openai``) import as ``hermes_plugins.image_gen__openai`` without colliding with any future ``tts/openai``. rzNo __init__.py in rcJg|]}|ks|| Sr:rrnr stale_prefixs r1rz8PluginManager._load_directory_module..s5^^^1qK/?/?1<.s5bbbq1 3C3Cq||T`GaGa3C3C3C3Cr3)r rrr2rrKmodulestypes ModuleType__path__ __package__rrrspec_from_file_locationrloader ImportErrormodule_from_spec exec_moduler[) rrrrrns_pkgrrRrrs ` @r1rz$PluginManager._load_directory_module{s(-(( . !! G#$E$E$EFF F S[ ( (%j11F FO!+F &,CK #!JT%@%@%J%J &((( ^^^^^ ^^^ " "D D!!~55  (+J'86   <4;.JyJJKK K0066(z??+#) K   K # #F + + + +    cbbbbCKbbb & &K%%   s 0F 5Gctj}t|dr|t }n=t |tr|t g}n d|D}|D](}|j |j kr| cS)td|j dt d)z:Load a pip-installed plugin via its entry-point reference.rrc2g|]}|jtk|Sr:)rr)rrs r1rz9PluginManager._load_entrypoint_module..s%LLLRX9K-K-K-K-K-Kr3z Entry point 'z' not found in group 'r) rrr~rrrrrrrr1r)rrrrrs r1rz%PluginManager._load_entrypoint_modules --// 3 ! ! M ); <.sC   Ng/; ;      r3ci|];\}}|vr2|jtjjtjjhv8||.sf    ez!!4 %!7!. %r3r:)r! signaturer(r?r@rr rC)rraccepted_payloadr(s @r1_invoke_hook_callbackz#PluginManager._invoke_hook_callbacks ' *844?JJ:& ' ' '8&&g&& & & & '   '..00      '8&&g&& &     &}}    x++*+++s 99r List[Any]c |dkr|dt|j|g}g}|D]} |||}|||1#t $rC}td|t|dt||Yd}~yd}~wwxYw|S)uCall all registered callbacks for *hook_name*. Hook payloads evolve additively. Callbacks that accept ``**kwargs`` receive the complete payload; older callbacks with a narrow signature receive only the keyword arguments they declare. Each callback is wrapped in its own try/except so a misbehaving plugin cannot break the core agent loop. Returns a list of non-``None`` return values from callbacks. For ``pre_llm_call``, callbacks may return a dict describing context to inject into the current turn's user message:: {"context": "recalled text..."} "recalled text..." # plain string, equivalent Context is ALWAYS injected into the user message, never the system prompt. This preserves the prompt cache prefix — the system prompt stays identical across turns so cached tokens are reused. All injected context is ephemeral — never persisted to session DB. rstelemetry_schema_versionNz Hook '%s' callback %s raised: %sr6) rrrrr+rrrQrArr)rrrrresultscbretrs r1 invoke_hookzPluginManager.invoke_hooks6 0 0 0   8:Q R R RKOOIr22   B 00V<<?NN3'''   6B DHH55  s-A22 B?<9B::B?rct|stdt||}|j5|j|g|ddddS#1swxYwYdS)z=Add an owner-tagged event subscription in registration order.z*Event subscriber callback must be callable)rrN)rr?rrrrr)rrrrrVs r1rzPluginManager._subscribe_events!! JHII I"BBB   D D   * *5" 5 5 < PluginManager._remove_plugin_subscriptions..:s%OOOe%+:N:NE:N:N:Nr3N)rrrr)rrremovedrrUretaineds ` r1rz*PluginManager._remove_plugin_subscriptions*s   3 3d122 3 3-e4OOOOwOOO3w<<#h--77319D'..+E22 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3 3sA*BB Bc|j5|j}|jdu}|xjdz c_|jt jt|_d|_|j |jd | }n#t j $rYnWwxYw |tur||j|n#|wxYw~|r|t|jddddS#1swxYwYdS)z@Cancel the current event generation and clear its subscriptions.Nrrr)rrrrrrFrrrrr get_nowaitEmpty_EVENT_WORKER_STOP_mark_event_doner task_done put_nowaitr notify_all)r old_queue had_workerrs r1_reset_event_buszPluginManager._reset_event_busBs   * *)I+47J  " "a ' " "   % % ' ' ' % 4F G G GD !%D   - 8 8&    *$//11DD{E*#555--do>>>''))))I'')))) * 9$$%7888   ' ' ) ) )5 * * * * * * * * * * * * * * * * * *sNBE  BE B1.E 0B11E 5#C-E -D9E  E E c|j}||rdS|j}tj|j|fdd}||_|dS)Nzhermes-plugin-eventsT)r rrdaemon)ris_aliverrThread_event_worker_loopr)rworkerdispatch_queues r1_ensure_event_worker_lockedz)PluginManager._ensure_event_worker_locked`sp#  &//"3"3  F*!* "'     $ r3rIqueue.Queue[Any]c |} |tur: |tur||j|dS|||tur||j|n<#|tur||j|wxYwr)rr;r<rr=_deliver_event)rrIrs r1rGz PluginManager._event_worker_loopns +!%%''D +---111))$/:::((***** ##D)))111))$/:::((****111))$/:::((**** +s B'B''9C rc|j5|j|d}|dkr |dz |j|<|jddddS#1swxYwYdS)Nrr)rrrr?)rrpendings r1r<zPluginManager._mark_event_donezs   * *7;;JJJG{{@G! 1*=   ' ' ) ) )  * * * * * * * * * * * * * * * * * *sAAA!$A!rrc H|j5|j|jkr ddddS dddn #1swxYwYt|jdd}|j|j_ |jD]|j5|j|jkr dddntfd|j |j gDs dddo dddn #1swxYwYj } tj|j}|di|}t!|#t"$rI}t$d|j t|dt)||Yd}~d}~wwxYw||j_dS#||j_wxYw)z9Deliver one queued event on the host-owned worker thread.Nrrc3 K|]}|uV dSrr:)rr subscriptions r1rz/PluginManager._deliver_event..s<# </r3z#Event '%s' subscriber %s raised: %sr6r:)rrrrrrrrrrrrrcopydeepcopyrresolve_plugin_command_resultrrQrAr)rrprevious_depthr owned_payloadrrrRs @r1rMzPluginManager._deliver_events    $"888        8               !!17A>>!% 4 $ 2   % ! !$*@@@ ! ! ! ! ! ! ! ! '+':'>'>tz2'N'N!! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! ! !(0 %)M$,$?$?M%X66 66F1&9999 NN= *d8nnEE &4D  " " "^D  " 3 3 3 3sx599(F9C+ F:C+ F F+C/ /F2C/ 3 F>0D/.F/ F9>E=7F=FFF!@rr2cj5jjfd|cdddS#1swxYwYdS)zCWait for the current event generation to become idle (test helper).cBjddkS)Nr)rr)rrsr1rz8PluginManager._wait_for_event_dispatch..s 9==j!LLPQQr3rN)rrwait_for)rrrs` @r1_wait_for_event_dispatchz&PluginManager._wait_for_event_dispatchs    /J#,,QQQQQ-                  s'>AAcXt|jdd}|tkr#tdt|dS|j5t |j|g}|s ddddS|j }|j |d}|tkr/tdt| ddddSt|t|||dz|} |j|nB#t j$r0tdt|YddddSwxYw|dz|j |<|t'|cdddS#1swxYwYdS)a7Queue *event* without blocking; return subscriber count scheduled. A single daemon worker preserves registration order. Pending work is bounded per manager generation so a blocking subscriber can consume at most one worker while later emits are dropped once the budget is full. rruoEvent bus recursion cap (%d) exceeded while dispatching '%s' — dropping this emit to prevent an infinite loopNuUEvent bus pending budget (%d) exhausted while dispatching '%s' — dropping this emitr)rrrrr)rr_EVENT_EMIT_DEPTH_CAPrQrArrrrrrrrrrr>rFullrJr)rrrrrrrOrs r1rzPluginManager._dispatch_eventss('155 ) ) ) NNE%u    1  ! &! &!$"5"9"9%"D"DEEM  ! &! &! &! &! &! &! &! &/J7;;JJJG,,,2&  ! &! &! &! &! &! &! &! &&W +ai% D !,,T2222:   2&  =! &! &! &! &! &! &! &! &. =DaKD -j 9  , , . . .}%%C! &! &! &! &! &! &! &! &! &! &! &! &! &! &! &! &! &! &sC ,FAF!$FD! F!0E FE  2FF#&F#cPt|j|S)z@Return True when at least one callback is registered for a hook.)rBrrrrs r1has_hookzPluginManager.has_hooksDKOOI..///r3tuple[Callable, ...]cRt|j|dS)#t$r1}t d|j |j|Yd}~d}~wwxYwt!|t"s;t d|j |jt%|j|} | s't| vs t | vr(t d|j |jat| |jkr %d) and was skippedzePlugin system prompt section %s (%s) exceeded the aggregate session budget (%d chars) and was skipped)rrrrzCSession plugin prompt section: id=%s plugin=%s position=%s chars=%d)rMappingProxyTyperrrrrDrMAX_SYSTEM_PROMPT_SECTIONSrQrArrrrrrrr;r6rErr&MAX_SYSTEM_PROMPT_SECTIONS_TOTAL_CHARSrrrr+) rrh frozen_inforendered total_charsrrrrtextrendered_charss r1render_system_prompt_sectionsz+PluginManager.render_system_prompt_sectionss ,T,-?-?@@ <>/0037J3K3KKaO  !=>>P P J2:>G8}} :::2J.    00)GOOK000     UJN   eS)) XJNKK(  ;;==D $,,0Ct0K0K9JN  4yy7,,,0JNII%  !=gj$!O!OPPN $!#^+.TTT@JN:  OO1z $-">     > )K KKU  D     s40C%% D /'DD cPt|j|S)zDReturn True when at least one callback is registered for middleware.)rBrr)rrs r1has_middlewarezPluginManager.has_middlewareDs!D$((..///r3c *|j|g}g}|D]r} |di|}|||##t$rC}td|t |dt||Yd}~kd}~wwxYw|S)a Call registered middleware callbacks for *kind*. Each callback is isolated so one plugin cannot break the base runtime path. Middleware that wants to change behavior must return the shape documented by the caller-specific contract. Nz&Middleware '%s' callback %s raised: %sr6r:)rrrrrQrArr)rrrrr/r0r1rs r1invoke_middlewarezPluginManager.invoke_middlewareHs$((r22   B bll6ll?NN3'''   <B DHH55  sA B 9B  B List[tuple]c*t|jS)aaReturn the list of plugin-registered Slack action handlers. Each entry is a ``(action_id, callback, plugin_name)`` tuple. Consumed by the Slack adapter at connect time to wire callbacks into its ``slack_bolt.AsyncApp``. Plugins register handlers via :meth:`PluginContext.register_slack_action_handler`. )rrrs r1get_slack_action_handlersz'PluginManager.get_slack_action_handlerscsD/000r3rcg}t|jD]\}}||jj|jjp |jj|jj|jj|jj |jj |j t|j t|jt|jt|j|jd |S)z7Return a list of info dicts for all discovered plugins.) rrrrrrrtoolsrrcommandsr)rDrPrCrrrrrrrrrrrrrrr)rrrrQs r1 list_pluginszPluginManager.list_pluginsss')!$-"5"5"7"788  KC MM"O0!?.F&/2F"O0%6#)?#>$o4%~ !899 !899"%f&B"C"C #F$> ? ?#\        r3qualified_nameOptional[Path]cN|j|}|r|dndS)z>Return the ``Path`` to a plugin skill's SKILL.md, or ``None``.rN)rr)rrrVs r1find_plugin_skillzPluginManager.find_plugin_skills+#''77 %/uV}}4/r3rrZcr|dtfd|jDS)zCReturn sorted bare names of all skills registered by *plugin_name*.rc3XK|]$\}}||dV%dS)rNr )rqnrKr1s r1rz3PluginManager.list_plugin_skills..sQ  A}}V$$ kN      r3rDrrC)rrr1s @r1list_plugin_skillsz PluginManager.list_plugin_skillssX"""    ,2244      r3cbdt|jDS)zDReturn progressive-disclosure metadata for registered plugin skills.c g|]N\}}|t|dddt|didOS)rr<rr)rrcategoryr)rrr)rrrVs r1rz.sm   ! 5 ""599]B#?#?@@$#EIImR$@$@AA      r3rrs r1list_plugin_skill_metadataz(PluginManager.list_plugin_skill_metadatas<  %+4+>+D+D+F+F$G$G    r3Dict[str, Dict[str, Any]]cHd|jDS)z?Return a defensive copy of enabled portable MCP server configs.c4i|]\}}|t|Sr:)r)rrrs r1rmz:PluginManager.get_portable_mcp_servers..s4   f $v,,   r3)rrCrs r1get_portable_mcp_serversz&PluginManager.get_portable_mcp_serverss2  $ : @ @ B B    r3c*t|jSr)rBrrs r1has_portable_mcp_serversz&PluginManager.has_portable_mcp_serverssD.///r3c<|j|ddS)z>Remove a stale registry entry (silently ignores missing keys).N)rr)rrs r1remove_plugin_skillz!PluginManager.remove_plugin_skills! 55555r3r)rrfr'rC) rrrrrrrrr'r)r rr r r'rB)rrrrrr r'rC) rr8rrrr rvrr'rB)rrrr rvr r'rB)rrr'rC)r r!r'rC)rr.r'rrr2r'rBr)rrrOrPr'rC)rrr'rC)rr r'rBFrArBr'rCr)rrrr rXrr'rC)rr)r'rrrr'rB)rr rrrrr'r) rr rrrrr1rrr0r'r) rr rr rrr1rr'rr)rrr'r)rrr'rC)rrrQrr'rCr)rrrrfr'r )rrr'r )rr rr8r'r rrrr r'r,)rrrrrr r'rC)rrr'r0)rIrKr'rC)rr0r'rC)rrr'rC)rX)rr2r'rB)rrrr8r'r0rrr'rBrrr'rdrhrr'rirrr'rBrrrr r'r,r'rxr'r)rrr'r)rrr'rZ)r'r)rrr'rC)Jr6r7r8r9r#rrrCrrrr(rrrr-r1r5r4rrrRrTrr\rZrYrXrrrlrrrrrrmrrrorrqrrrrnrrrrrrr+r2rrrBrJrGr<rMr]rrcrgrsrurwrzr~rrrrrrr:r3r1rrA s,EEI;I;I;I;I;^,\ # # # #    22226666====."\BF/////BFvvvvvx:::X:;;;;2222 ----(((((TQQQQ5S5S5S5Sn\\\\| U U U UD1111f6666@*.      2TTTTlTTTTt& & & & P / / / /"&UAUAUAUAnxxxxt%%%%NGGGG8     //// S>S>S>S>j2+2+2+2+h 1 1 1 15555&* AAAAAAF    ,,,,\,6++++Z D D D D0****<     + + + +****#4#4#4#4J1&1&1&1&f00005555XXXXt00006 1 1 1 1 40000              0000666666r3rOptional[PluginManager]_plugin_managerzDict[Path, PluginManager]_plugin_managers_by_homec tS#t$r#tcYSwxYw)a Return the profile/home key for process-global plugin state. Plugins are discovered from ``get_hermes_home() / "plugins"`` and some plugins (notably context engines such as hermes-lcm) capture that home at registration time for profile-scoped storage. A long-lived process can temporarily switch Hermes home (env var *or* the context-local ``set_hermes_home_override()``) while serving another profile, so the plugin manager must be scoped to the active Hermes home instead of being one process-wide singleton. )r expanduserr.rr:r3r1_plugin_home_keyrsd.  ++--55777 ...  ++-----.s14*A! A!rFc|dSt|diD]}t|dd}t|ddrtdsDdfdtjDD]}tj|=t 5t|j krt ddddn #1swxYwYdS)aPurge ``sys.modules`` entries for directory-loaded plugins. ``PluginManager._load_directory_module`` imports each plugin as ``hermes_plugins.`` and registers that top-level module in ``sys.modules``. Anything the plugin's ``__init__.py`` imports with a *relative* import (``from . import foo``, ``from .sub import bar``) ends up cached in ``sys.modules`` too, under ``hermes_plugins..``. When we swap in a fresh manager for a new home, replacing only the parent module leaves those submodules behind: if a same-named plugin in the new profile does a relative import, Python resolves it from ``sys.modules`` first and silently reuses the *previous* profile's already-imported submodule (and any module-level state it captured), instead of re-executing the new profile's code. We must evict the package itself and every module whose name is prefixed with ``"."`` before (or when) discarding a manager, not just drop our reference to it. NrPrr6rcJg|]}|ks|| Sr:r )rrrr1s r1rz,_clear_plugin_submodules..s5XXX1qK/?/?1<&E&E&G&GHHII  &?(+J+J OOO , , , Q QG $W - - - Q     Q Q Q @4 PPPPP Q &&(((                  s6AtjrdSt5t'tr ddddSdfd }t j|ddatddddS#1swxYwYdS) uERun plugin discovery in a daemon thread (startup-latency overlap). Discovery costs ~150ms of manifest scanning + module imports on the CLI startup path. Interactive chat doesn't need plugins until the first agent turn, so callers on that path can start discovery here and let it overlap the CPU/subprocess-heavy rest of startup. Every synchronous consumer goes through :func:`discover_plugins`, which joins this thread first — so no caller can observe a half-loaded registry. Idempotent; no-op when discovery already ran or is already in flight. Nr'rCc tdS#t$r tddYdSwxYw)Nz"background plugin discovery failedTr)r\_persist_plugin_toolset_keysrrQrArFsr1_runz/start_background_plugin_discovery.._runhsl T))+++,..... T T TCdSSSSSS Ts"'&AAzplugin-discoveryTr rrDr)rr_background_discovery_lockrrErrFr)rrFs @r1!start_background_plugin_discoveryrUs'!""G #-- ' 38T8]8]8_8_ 3 -------- T T T T T T(1'70( ( ( $ %**,,,------------------s"B6BBBrrr2ct}|)|r|tjurdS||dS)zGWait for an in-flight background discovery (no-op from its own thread).Nr[)rrErcurrent_threadr)rr>s r1rrusJ$Ay yY-E-G-G(G(GFF7Fr3c.ddlm}|dz dz S)Nrrcachezplugin_toolset_keys.json)hermes_constantsrrs r1_plugin_toolset_keys_cache_pathr}s-000000 ?  w &)C CCr3c ddl}ddl}ddl}tdt D} tt }n#t$rg}YnwxYwt}|j dd| t|j d\}}| |dd 5}|||d |dddn #1swxYwY|||dS#t$r t d d YdSwxYw)zJPersist discovered plugin toolset keys + portable MCP names (best-effort).rNch|]\}}}| Sr:r:rts_keyrs r1rz/_persist_plugin_toolset_keys..sHHH,&!QvHHHr3Trz .pt_keys.)dirr1wrr/) toolset_keys portable_mcpz!plugin toolset key persist failedr)r0r+tempfilerDget_plugin_toolsetsrrrrr/r mkstemprfdopendumprrQrT) _json_os _tempfilerErrfdtmpfhs r1rrsI$$$$HH2E2G2GHHHII 022KKMMNNHH   HHH .00 $666##DK(8(8#MMC ZZC'Z 2 2 Mb JJhGG L L L M M M M M M M M M M M M M M M C III 84 HHHHHHIsY1D+-A"!D+" A1.D+0A11A1D+"D< D+D  D+D D++&EErc ddl}|td}t |t r|Sn#t $rYnwxYwdS)Nrrr/)r0rrrrrr)rblobs r1_read_plugin_keys_cachers {{ + - - 7 7 7 I I   dD ! ! K       4sAA A A  'set[str]'ct}t}|jr.||sdt DS|v|rbt }|R|d}t|tr(td|Drt|Stdt DS)u@Plugin toolset keys without blocking on in-flight discovery. When discovery already completed in this process, reads the live registry. While a background discovery is still running, falls back to the key set persisted by the previous run — callers on the startup path (platform toolset resolution) only use these keys to EXCLUDE plugin toolsets from composite expansion, so a stale set from the last launch is harmless and self-heals as soon as discovery lands. When neither is available, blocks via discover_plugins() (correctness first). Nch|]\}}}| Sr:r:rs r1rz1get_plugin_toolset_keys_nowait..sAAA<61aAAAr3rc3@K|]}t|tVdSrrrks r1rz1get_plugin_toolset_keys_nowait..s,-O-OQjC.@.@-O-O-O-O-O-Or3ch|]\}}}| Sr:r:rs r1rz1get_plugin_toolset_keys_nowait..s = = =|vq!F = = =r3) rrrrErrrrrrrr)rFr>rrEs r1get_plugin_toolset_keys_nowaitrs!""G$AB  AA+>+@+@AAAA}}&((  88N++D$%% !#-O-O$-O-O-O*O*O !4yy  = =':'<'< = = ==r3ct}t}|jr7||s!t |S|v|rbt }|R|d}t|tr(td|Drt |Stt |S)aPortable MCP server names without blocking on in-flight discovery. Same contract as :func:`get_plugin_toolset_keys_nowait`: live registry when discovery finished, last launch's persisted set while a background discovery is running, blocking discovery otherwise. Nrc3@K|]}t|tVdSrr)rrs r1rz7get_portable_mcp_server_names_nowait..s,.Q.Qaz!S/A/A.Q.Q.Q.Q.Q.Qr3) rrrrErrrrrrrr)rFr>rnamess r1$get_portable_mcp_server_names_nowaitrs!""G$A7  73355666}}&((  HH^,,E%&& "3.Q.Q5.Q.Q.Q+Q+Q "5zz! w//11 2 22r3rr2c`tt|S)zUnload one plugin or all plugins from the process-global manager. Wait for background discovery first so teardown cannot race an in-flight registration sweep introduced by the warm-start discovery path. )rrr5r0s r1unload_pluginsrs*      & &v . ..r3ct}t|dds"t||S)uReturn the active manager, lazily running discovery if it never ran. Hook/middleware delivery must not depend on WHICH surface imported us: dashboards, TUI slash workers, query mode, and cron delivery paths never import ``model_tools`` (whose import side-effect is the discovery trigger on the interactive CLI path), so hooks registered by user plugins were silently dead on those surfaces (#50776, #67597, #67890, #50937; tracking #64178 — salvaged from PR #64188). ``getattr`` with a ``True`` default so test doubles that monkeypatch ``get_plugin_manager()`` with a bare namespace are invoked untouched. rT)rrrr\rs r1_delivery_managerrsF!""G 7M4 0 0$"$$$!!### Nr3rrr,c 6tj|fi|S)aInvoke a lifecycle hook on loaded plugins. Ensures plugins are discovered on first invocation so callers in processes that never explicitly call ``discover_plugins()`` (gateway platform events, TUI slash workers, query mode, cron) still fire callbacks registered by user plugins (tracking #64178). Returns a list of non-``None`` return values from plugin callbacks. )rr2)rrs r1r2r2s& +    *9 ? ? ? ??r3rhricDt|S)z@Render plugin prompt sections after idempotent plugin discovery.)_ensure_plugins_discoveredrs)rhs r1rsrss & ' ' E El S SSr3rc 6tj|fi|S)uInvoke registered middleware callbacks. Lazy-discovers plugins on first use — same delivery-parity guarantee as :func:`invoke_hook` (tracking #64178). Returns a list of non-``None`` return values from middleware callbacks. )rrw)rrs r1rwrws& 1    0 @ @ @ @@r3c.t}t|ddst}t|dd}t|rt ||St t|di|S)aReturn True when middleware callbacks are registered for ``kind``. Lazy-discovers first: callers use this as a gate before :func:`invoke_middleware`, so a pre-discovery ``False`` here would silently skip delivery on surfaces that never ran discovery (#64178). rTruNr)rrrrrBr)rrFrs r1rurus!""G 7M4 0 0&#%% W. 5 5F"FF4LL!!! 3377== > >>r3cDt|S)uReturn True when a loaded plugin handles a hook. Lazy-discovers first — same gate-before-invoke rationale as :func:`has_middleware` (tracking #64178). )rrcrs r1rcrc!s    ' ' 2 22r3rdcDt|S)rf)rrgrs r1rgrg*s    3 3I > >>r3)rrsurfacer alias_usedargs_rawrrc n t}|dsdS|d||||||}|D]<}t|tr%d|vsd|vrt d|||=dS#t$r&} t d| Yd} ~ dSd} ~ wwxYw)afFire the ``pre_command`` observer hook (#64204). Never raises. Observer-only in v1: return values are ignored. If a plugin returns a directive-shaped dict (``action``/``decision`` keys), a debug line is logged so future block/rewrite adopters are discoverable when the middleware variant ships against the #64231 command-event taxonomy. rXN)rrrrrractiondecisionzpre_command is observer-only in v1: ignoring directive %r for /%s (surface=%s). Block/rewrite will arrive with the command middleware variant (#64204/#64231).z0pre_command hook dispatch failed (non-fatal): %s)rrcr2rrrQrTr) rrrrrrrFr/rrs r1fire_pre_command_hookr/s N$&& ..  F%% !#&    F&$'' F""jF&:&: FGW    NNN GMMMMMMMMMNs#BAB B4B//B4cHeZdZUdZded<dZded<dZded<dZded<dS)_PreToolCallDirectiveNrfrrrule_keyr modified_args)r6r7r8rrrrrr:r3r1rr]sV F    !G!!!!"H"""".2M222222r3r>Tool '{tool_name}' denied: not in this thread's tool whitelistallowedr deny_msg_fmtc6|t_|t_dSr)_thread_tool_whitelistrfmt)rrs r1set_thread_tool_whitelistres&-"!-r3cdt_dSr)rrr:r3r1clear_thread_tool_whitelistrms%)"""r3rrrtask_id session_id tool_call_idturn_idapi_request_idmiddleware_traceOptional[List[Dict[str, Any]]]c ttdd}|?||vr;ttdd} td| |Sdd lm} | d |t |tr|ni|||||t|pg } d} d} | D]N}t |ts| d d krj| d}t |tr?|r=| &t |trt|ni} | || d }|dvr| d}t |tr|r|nd}|dkr|s|dkr| dnd}t |tr| nd}|sd}t|||| cSt| S)u@Check ``pre_tool_call`` hooks for a blocking or approval directive. Plugins that need to enforce policy (rate limiting, security restrictions, approval workflows) can return one of:: {"action": "block", "message": "Reason the tool was blocked"} {"action": "approve", "message": "Why this needs human confirmation"} {"action": "approve", "message": "...", "rule_key": "write_file:ssh"} from their ``pre_tool_call`` callback. - ``block`` vetoes the tool call outright (the message becomes the tool result the model sees). - ``approve`` ESCALATES to the existing human-approval gate (``prompt_dangerous_approval`` on CLI, the approval callback on the gateway) — the same mechanism Tier-2 dangerous shell patterns use. This lets a plugin require a human ``[o]nce/[s]ession/[a]lways/[d]eny`` decision on ANY tool, not just terminal command strings. The caller is responsible for invoking the gate (see :func:`tools.approval.request_tool_approval`). - ``rule_key`` is optional and only honored for ``approve`` directives. It lets plugins choose the allowlist grain for `[a]lways` approvals. The first valid directive wins. Invalid or irrelevant hook return values are silently ignored so existing observer-only hooks are unaffected. rNrzTool '{tool_name}' deniedblock)r)rrr)r2r\)rrrrr r r r rmodifyr)rapproverrr)rrrr)r) rrrrphermes_cli.lifecycler2rrrrrCrrE)rrrrr r r r rrinvoke_lifecycle_hook hook_results block_msgrrrhrrrs r1$_get_pre_tool_call_directive_detailsrqslH,i>>Gy77,e5PQQ$JJJ33    JIIIII((d++ 3TT!%.4"55   L $I.2M  &$''   ::h  8 + +jj((G'4(( .W . (2>###d H$7X'      !} = = ==r3#tuple[Optional[str], Optional[str]]c Lt||||||||}|j|jfS)aDCheck ``pre_tool_call`` hooks for a blocking or approval directive. Backward-compatible public helper: returns ``(directive, message)`` where ``directive`` is ``"block"``, ``"approve"``, or ``None``. Internal callers that need approve-specific metadata use :func:`_get_pre_tool_call_directive_details`. rrr r r r )rrr rrrrr r r r detailss r1get_pre_tool_call_directivers="34Z!7%8HG NGO ,,r3c Jt||||||||\}} |dkr| ndS)aZBack-compat shim: return only a ``block`` message (or ``None``). Deprecated in favor of :func:`get_pre_tool_call_directive`, which also surfaces the ``approve`` escalation directive. Kept so any external caller importing the old name keeps working; ``approve`` directives are invisible to this shim (it only reports blocks). rrN)r) rrrrr r r r  directivers r1get_pre_tool_call_block_messagersG"54Z!7%8HIw  7**774r3c Xt||||||||}t|||||S)aResolve the pre_tool_call directive to a final block message (or None). Single entry point for every tool-dispatch site: fetches the plugin directive and, for an ``approve`` escalation, invokes the human-approval gate (:func:`tools.approval.request_tool_approval`). Returns the message the tool result should carry when the call is blocked, or ``None`` when the call may proceed. Centralizing this keeps the security-critical fail-closed logic in ONE place instead of copy-pasted across the concurrent/sequential/helper dispatch paths: an ``approve`` directive whose gate errors, denies, or times out is fail-closed to a block; ``block`` blocks with its message; anything else proceeds. rr r r)r_resolve_block_from_detailsrs r1resolve_pre_tool_blockr#sQ034Z!7%8HG 'lz   r3r!r'_PreToolCallDirective'c|jdkr|jS|jdkr ddlm}m}m}d} ||||}n#t $rYnwxYw |||jpd|jp|} | ||n5#t $rYn)wxYwn$#| ||w#t $rYwwxYwwxYwn#t $rd |cYSwxYw| d s't| d pd |SdS) aResolve a fetched directive to a final block message (or ``None``). Shared by :func:`resolve_pre_tool_block` and :func:`_dispatch_pre_tool_call_hooks` so the security-critical fail-closed approval logic lives in exactly ONE place: ``block`` blocks with its message; an ``approve`` directive whose gate errors, denies, or times out is fail-closed to a block; anything else proceeds. rrr)request_tool_approval#reset_current_observability_context!set_current_observability_contextNr!r<)rz)BLOCKED: plugin approval gate failed for approvedrz&BLOCKED: plugin approval required for ) rrtools.approvalr&r'r(rrrr) rrr r rr&r'r(approval_tokensrs r1r"r"'s"~  ~"" K           #O "C"C#!-)###      ..O)r$-: #.;;OLLLL$/?.;;OLLLL$/  K K KKyJJ J J J Kzz*%%  9%%HGIGG  4s B-;B- AB-AB- B(B-+ A76B-7 BB-BB-B) BB) B%"B)$B%%B))B--B?>B?.Tuple[Optional[str], Optional[Dict[str, Any]]]c jt||||||||}t|||||} | |jfS)uInvoke ``pre_tool_call`` hooks once and process all response types. Returns a ``(block_message, modified_args)`` tuple: - ``block_message`` — the first block/approve directive's resolved message (or ``None`` when the call may proceed). Shares the exact fail-closed approval-gate logic of :func:`resolve_pre_tool_block` via :func:`_resolve_block_from_details`, including the observability context set around the human-approval gate. - ``modified_args`` — merged args from ``modify`` directives (or ``None`` when no hook requested modification). This is the single invocation point for ``pre_tool_call`` hooks. Callers that only need block detection should keep using :func:`get_pre_tool_call_block_message` or :func:`resolve_pre_tool_block` for backward compat. Callers that also need input transformation should call this function and apply ``modified_args`` if not ``None``. rr!)rr"r) rrrrr r r r rrs r1_dispatch_pre_tool_call_hooksr.cs^834Z!7%8HG ,lzI w, --r3rrrcodingattemptfinal_response changed_pathsrr0r1r2r3Optional[List[str]]c td||||||t|pg}|D]}t|tst |dp|dpd} | dvrz|dp|d} t| tr*| r| cSd S) u9Check user ``pre_verify`` hooks for a directive to keep the agent going. Fired once per turn when the agent edited code and is about to verify/finish. A hook keeps the turn going (run a check, defer it, tidy the diff) by returning:: {"action": "continue", "message": ""} The Claude-Code Stop shape ``{"decision": "block", "reason": "..."}`` (block the stop == keep going) is accepted too. The first directive carrying a non-empty message wins; any other return lets the turn finish. Mirrors :func:`get_pre_tool_call_block_message` — the call site stays a one-liner. ``coding`` / ``attempt`` let a hook scope itself (``if not coding`` …) and self-throttle (``if attempt`` …), the same way a ``pre_tool_call`` hook scopes on ``tool_name``. rWr/rrr<)continuerrreasonN)r2rrrrrrErF) rrrr0r1r2r3rrrrs r1get_pre_verify_continue_messager8s6%=.B//   L##&$''  VZZ))IVZZ -C-CIrJJPPRRXXZZ . . . **Y''?6::h+?+? gs # # #  #==?? " " " 4r3 r2r status_code error_type error_code error_message error_bodyr approx_tokenscontext_length num_messagesr2r:rr;r<r=r>rOptional[BaseException]r?r@rAc jddlm} td||||||t|tr|ni||| |  } d} d}| D]S}t|ts|d}t|| r|}nWt|t rA | |}n#t$rYwxYw| |dz }d|i}dD]}||vrt||||<|d }t|t r3|r|dd |d <|d }t|tr||d <|} U| |rt d || S) uACheck ``transform_api_error_classification`` hooks for a directive. Consulted by :func:`agent.error_classifier.classify_api_error` BEFORE its built-in pipeline, so a provider plugin can both add classifications the core patterns miss and correct ones they get wrong for its provider. A callback returns ``None`` to decline, or a dict with a required ``"reason"`` (a :class:`agent.error_classifier.FailoverReason` member or its string name) plus optional recovery-hint overrides. Dispatch is run-all-then-pick-first: ``invoke_hook`` runs every registered callback with failures isolated, then the first result carrying a valid reason wins in registration order — mirroring :func:`get_pre_tool_call_block_message`, invalid or irrelevant returns are silently ignored so a misbehaving plugin degrades to a no-op. When more than one callback returns a valid classification, the losing results are skipped with a runtime warning (the #64714 skipped-transform rule) so conflicting provider plugins are visible in logs instead of silently shadowed. Privacy: ``error_message`` and ``error_body`` may carry an unredacted provider error dump; callbacks must not log or forward them without redaction. Cold path: fires only on API failure, never on the request hot path. Contract: the transform-family first-valid-wins shape in ``docs/plugins/hook-taxonomy.md``. Returns a sanitized dict (``reason`` coerced to ``FailoverReason``, hint fields coerced to ``bool``) or ``None`` when no plugin claimed the error. r)FailoverReasonr{r9Nr7r) retryableshould_compressshould_rotate_credentialshould_fallbackri error_contextztransform_api_error_classification: skipped %d valid classification(s) after the first result in registration order won (run-all-then-pick-first)) agent.error_classifierrDr2rrrrrErFr@rBrQrA)r2rr:r;r<r=r>rr?r@rArDrwinner skipped_validr reason_rawr7rFrrrIs r1get_plugin_error_classificationrNs"X655555,#!+J!=!=E::2#%!   L(,FM!!&$''  ZZ)) j. 1 1 FF  C ( (  ' (8(8(:(:(@(@(B(BCC        Q M '0  - -C f}}s ,,C**Y'' gs # # 3  3$]]__TcT2C N ?33 mT * * 1#0C  m ,     Ms/C CCcNt}|||S)zReturn the global manager after ensuring plugin discovery has run. Pass ``force=True`` to rescan in the current process. r)rr\)rArFs r1rr*s+ !""G E*** Nr3c(tjS)z5Return the plugin-registered context engine, or None.)rr&r:r3r1get_plugin_context_enginerQ4s % ' ' 77r3Optional[Callable]cftj|}|r|dndS)zFReturn the handler for a plugin-registered slash command, or ``None``.rUN)rrr)rrVs r1get_plugin_command_handlerrT9s3 & ( ( 9 = =d C CE$ .5  $.r3rctjsS tjn$#t$rtjcYSwxYwiit jd fd }t j|dd}|  tstdtd d d vrd  d S)aResolve a plugin command return value, awaiting async handlers when needed. Sync CLI/TUI dispatch sites call plugin handlers from plain functions. If a handler is async, await it directly when no loop is running; if we're already inside an active loop, run it in a helper thread with its own loop so the caller still gets a concrete result synchronously. The threaded path is bounded by a 30s timeout so a hung async handler cannot wedge the terminal indefinitely. r'rCc tjd<n#t$r}|d<Yd}~nd}~wwxYwdS#wxYw)Nrr)rrunr[r)rryfailureoutcomers r1_runnerz.resolve_plugin_command_result.._runnerXsv &{622GG   ! ! ! GENNNNNN ! HHJJJJJDHHJJJJs%A 4/A 4A A#zhermes-plugin-command-awaitTrr[z5Plugin command async handler did not complete within z.0fsrrr)r! isawaitablerrr4rWrEventrFrwait"_PLUGIN_COMMAND_AWAIT_TIMEOUT_SECS TimeoutErrorr)rrZthreadryrXrYs` @@@r1rUrUBsK  v & & # """" ###{6"""""#!G(*G ?  D  *F  LLNNN 99?9 @ @  91 8 9 9 9    en ;;w  s0AADict[str, dict]c(tjS)uReturn the full plugin commands dict (name → {handler, description, plugin}). Triggers idempotent plugin discovery so callers can use plugin commands before any explicit discover_plugins() call. )rrr:r3r1get_plugin_commandsrdps & ' ' 88r3rc`tfdtjDS)aReturn all plugin-registered auxiliary tasks as a stable-ordered list. Each entry is the registration dict from :meth:`PluginContext.register_auxiliary_task`: ``{key, display_name, description, defaults, plugin}``. Triggers idempotent plugin discovery so callers can read the registry before any explicit ``discover_plugins()`` call. Sorted by ``key`` for deterministic ordering in pickers and tests. c*g|]}j|Sr:)r)rrlrFs r1rz.get_plugin_auxiliary_tasks..s! F F FaG q ! F F Fr3)rrDrrs@r1get_plugin_auxiliary_tasksrgys5)**G F F F F6'2D+E+E F F FFr3rct}|j5d|jDcdddS#1swxYwYdS)a_Return the inter-plugin event bus subscription registry. Returns a snapshot mapping each fully-qualified event name (``:`` or ``hermes:``) to subscriber callbacks in registration order. Owner ledger metadata stays private to the manager. Triggers idempotent plugin discovery before reading the snapshot. c.i|]\}}|d|DS)cg|] }|j Sr:)r)rrVs r1rz7get_plugin_subscriptions...s888uEN888r3r:)rrrUs r1rmz,get_plugin_subscriptions..s=   w 88888   r3N)rrrrCrs r1get_plugin_subscriptionsrks)**G      ")"8">">"@"@                     s#AA  A rxcDt}|jsgS ddlm}n#t$rgcYSwxYwi}i}|jD]O}||}|s|j}||g|j P|j D]J\}}|j D]=}||}|r$|j|vr||j|>Kg} t|D]} || } d| dd} | r| jjr | jj} n(dt|| } | | | | f| S)zReturn plugin toolsets as ``(key, label, description)`` tuples. Used by the ``hermes tools`` TUI so plugin-provided toolsets appear alongside the built-in ones and can be toggled on/off per platform. rru🔌 rrr)rrrrrrrrrrrPrCrrDrrtitlerrr)rFr toolset_toolstoolset_pluginrrVtsrrQrrrrdescs r1rrs !""G  % +++++++  +-M.0N/<< ""9--   ]  R((// ;;;;!)//11AA v0 A AI&&y11E A-77))%-@@@ A F''--##F++:sC006688::  rrrBr?r0r@r0rAr0r'r)rArBr'r)rrr'rR)rr r'r )r'rbr)r'rr)r9 __future__rrrSrimportlib.metadatarimportlib.utilr!r0rIr+rrrKrr contextlibr dataclassesrr functoolsrpathlibr typingr r r r rrrrrrrrrrrrregistration_lifecyclerr=rrrrrhermes_cli.middlewarerrhermes_cli.plugin_capabilitiesr r!r"r#rhermes_cli.relay_plugin_cutoverr$r%r&r2rrr`r5 getLoggerr6rQr,rErFrGrHrVr|rr}rrrrr frozensetrrrrlrmcompilerrrrrrrrr_rrr;rrrrrrrrrrrrr-rBrr0r2rBrrr6rWrbrrrrrrrrrrrrrrr,r)rLockrrrrrrrr rErrrrrrrrrrrrrrrrrrrrrr2rsrwrurcrgrrrrrrrrrr#r"r.r8rNrrQrTr_rUrdrgrkrr:r3r1rsB#"""""    %%%%%%((((((((dddddddddddddddddddddddddd ;:::::11111111;;;;;;;;KKKKKKKK  > > > >KKKK DDDo  8 $ $"1266<<>>DDFFK!6 bbb bbbbV)%,!C<<<<AAAAH(#,)^,<"="=*/'"').&)rz*IJJ(=%?;ZZZZ [[[[" VXX  (**%'''''****!!!!     D!e d ddddd + + + +//// $ $ $     6f 6v5\El Gw GW Gg * *     @@@@F%%%%PAAAAH&,7777tOOOOO K5K5K5K5K5K5K5 K5\ $ $ $ $  "  ' ' ' ' ' ' '  'N(RZ(LMM!*+W+W+W!X!X!rz"HII,244444*IN,,6 0 0 0 0 FFFF @@@@DF;F;F;F;F;F;F;F;RIIIIIIII`>t!6t!6t!6t!6t!6t!6t!6t!6~C,0////798888' ))...."::::BD,@@@@ 8 8 8 8 8<@????+Y^------@DDD IIII*    >>>>23333,>B / / / / /( @ @ @ @TTTTAAAA ? ? ? ? 3333????"&"(N(N(N(N(N(NV)** $33333333Y.....****7;^>^>^>^>^>H7;-----87;5555587;     N 999999~7;%.%.%.%.%.T)-000000j!%+/%)iiiiiiX888 //// &*"+ + + + \9999 G G G G     ******sCCC