߲jYz~UdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl mZddlmZmZmZmZmZmZmZmZddlmZej4dZhdZd ed <d hZd ed <d hZd ed<dZ dZ!dZ"d1dZ#e$dhZ%dZ&dZ'dZ(dZ)e jTdZ+dZ,dZ-dZ.d2dZ/d3dZ0d4dZ1dZ2dZ3d Z4e5Z6ed!"Gd#d$Z7ed!"Gd%d&Z8ed!"Gd'd(Z9ed!"Gd)d*Z:d+Z;d,Z<e5Z=d5d-Z>d6d.Z?Gd/d0Z@y)7zPlugin hook / middleware / event-bus / system-prompt-section dispatch. Mixed into :class:`hermes_cli.plugins.PluginManager`. ``_resolve_hook_callback_timeout`` stays on the origin (tests patch it there) and is looked up lazily. ) annotationsN) dataclass)AnyCallableDictListMappingOptionalSetUnion)OBSERVER_SCHEMA_VERSIONzhermes_cli.plugins> pre_verify pre_llm_call post_llm_callon_session_endpost_tool_callpre_api_requeston_session_startpost_api_requestapi_request_errorpre_auxiliary_callpost_auxiliary_calltransform_llm_outputtransform_tool_resulttransform_terminal_outputzSet[str]_HOOK_TIMEOUT_BOUNDED_HOOKS pre_tool_call_HOOK_TIMEOUT_FAIL_CLOSED_HOOKS subagent_stop_HOOK_CALLER_THREAD_HOOKSgN@z;pre_tool_call plugin callback timed out or is still runningc t|dt|}d|d|dt|jdt |dddS) uBlock directive for a fail-closed hook whose callback raised: names the callback and the error (truncated — a hook that embeds tool args in its exception must not grow the tool result) so the operator can tell a crashing guard from a slow one.__name__blockz plugin callback z raised z: Nactionmessage)getattrreprtyper#str) hook_namecbexc callback_names @/home/ubuntu/.hermes/hermes-agent/hermes_cli/plugins_dispatch.py_policy_error_block_directiver2;s^B DH5M#$5m_HTRUYM_M_L``bcfgjcklpmpcqbrs uu after_memoryi i@z^[a-z0-9][a-z0-9._-]{0,127}$z## Plugin Context: z%z#cbt|txrttj |S)zDReturn whether *value* is a stable, heading-safe section identifier.) isinstancer,bool_SYSTEM_PROMPT_SECTION_ID_RE fullmatch)values r1!is_valid_system_prompt_section_idr<Os& eS ! Yd+G+Q+QRW+X&YYr3c4t|dt|d|S)zJRender an auditable, length-framed block recoverable from the full prompt.z" )%_SYSTEM_PROMPT_SECTION_HEADING_PREFIXlen) section_idcontents r1format_system_prompt_sectionrBTs. 1 1*>,,/L>' LMr3c|sy|Dcgc]"}t|j|j$}}tddj |zdt zScc}w)z=Render the canonical container used for persistence recovery. z )rBidrAPLUGIN_SECTIONS_STARTjoinPLUGIN_SECTIONS_END)sectionsitemblockss r1format_system_prompt_sectionsrM[s[ NV Wd*477DLLA WF W# $B '&++f*= ="EXDY@Z ZZXs'Ahermes@T)frozencDeZdZUdZded<ded<ded<ded<ded <y ) PluginSystemPromptSectionz:A plugin-owned section rendered once for each new session.r,rFz.Union[str, Callable[[Mapping[str, Any]], str]]rApositionint max_charspluginNr# __module__ __qualname____doc____annotations__r3r1rSrSlsD G ;;MN Kr3rSc:eZdZUdZded<ded<ded<ded<y)!RenderedPluginSystemPromptSectionz4Validated prompt bytes frozen on the owning AIAgent.r,rFrArTrWNrXr]r3r1r_r_ws> G LM Kr3r_c&eZdZUdZded<ded<y)_EventSubscriptionz%Host-owned subscription ledger entry.r,ownerrcallbackNrXr]r3r1raras/ Jr3racNeZdZUdZded<ded<ded<ded <ded <d ed <y )_QueuedPluginEventz9Immutable dispatch envelope consumed by the event worker.r,eventDict[str, Any]payloadztuple[_EventSubscription, ...] subscriptionsrUdepth generationzcontextvars.ContextcontextNrXr]r3r1reres(C J 11 JO! r3reg>@g@cbdD]*}|j|}t|ts%|s(|cSy)uIdentity of the call this callback fires for, or ``None`` when the event has none. Concurrent invocations of the same tool in one session must not collapse into one gate key: they are different work, and treating the second as a duplicate drops the hook as if a callback had timed out (upstream #98382). The identity is already in the payload; nothing new is plumbed. Deliberately not ``api_request_id`` — one API request carries many tool calls, which would re-collapse the keys. ) tool_call_idturn_idN)getr7r,)kwargsfieldr;s r1_hook_call_identityrss7- 5! eS !eL r3cB|dks|tvry|tvxs|tvS)zCWhether *hook_name* should run under the non-blocking timeout path.rF)r rr)r-timeouts r1_hook_uses_callback_timeoutrvs+!|y$== 3 3 cyDc7ccr3ceZdZeddZeddZddZdd ddZ ddZ ddZ dd Z dd Z d d Z d!d Zd"d Zd#d$dZd%dZd&dZddZd'dZ d(dZe d)dZd*dZd+dZy),PluginDispatchMixinc tj|j}t d|jDr t |Stjjtjjh}|jDcic]\}}||vr||j|vr||c}}S#ttf$rt |cYSwxYwcc}}w)zThe slice of *payload* a callback accepts: everything for ``**kwargs`` (or un-introspectable) callbacks, only declared names for narrow legacy signatures.c3jK|]+}|jtjjk(-ywN)kindinspect Parameter VAR_KEYWORD).0ps r1 z.s%T1qvv**666Ts13) r} signature parameters TypeError ValueErrordictanyvaluesr~POSITIONAL_OR_KEYWORD KEYWORD_ONLYitemsr|)rcrhr keyword_kindsnamer;s r1_hook_callback_kwargsz)PluginDispatchMixin._hook_callback_kwargss ! **84??J T @Q@Q@ST T=  **@@'BSBSB`B`a +2==? 'D%z!j&6&;&;}&L %K  :& !=  !  sB9"C9CCc Jddlm}||di|j||S)aBInvoke a hook while withholding additive fields from narrow legacy callbacks. An ``async def`` callback returns a coroutine; resolve it the way plugin slash commands are (loop-safe), otherwise the bare coroutine object is appended to the results and the plugin's body never runs (#12449). rresolve_plugin_command_resultr])hermes_cli.pluginsrr)clsrcrhrs r1_invoke_hook_callbackz)PluginDispatchMixin._invoke_hook_callbacks* E,X-e8Q8QRZ\c8d-effr3c ddlm}|dk7r|jdtg}|}t ||}|t v}|j j|gD]a} |r7|j||||} | tur-|r|jdtd=|j||} | |j| c|S#ttf$r<} |j|||| |r|jt!||| Yd} ~ d} ~ wwxYw)a>Call all callbacks for *hook_name*; return their non-``None`` results. Payloads evolve additively: ``**kwargs`` callbacks get everything, narrow signatures only what they declare. Each callback is isolated. Bounded hooks and ``pre_tool_call`` run under ``plugins.hook_callback_timeout`` (worker abandoned, never joined); ``pre_tool_call`` fails closed with a block directive, others skip. ``_HOOK_CALLER_THREAD_HOOKS`` always run on the caller thread. ``pre_llm_call`` may return ``{"context": "..."}`` (or a str) to inject. r_resolve_hook_callback_timeoutgateway_platform_eventtelemetry_schema_versionr$r&N)rr setdefaultr rvr_hooksrp_run_hook_callback_bounded _HOOK_SKIPPEDappend$_PRE_TOOL_CALL_TIMEOUT_BLOCK_MESSAGEr Exception SystemExit_report_hook_failurer2) selfr-rqrresultsru use_timeout fail_closedr.retr/s r1 invoke_hookzPluginDispatchMixin.invoke_hooks F 0 0   8:Q R021)WE #BB ++//)R0 VB V99)RQXYCm+&#NNgJn+op 44R@C?NN3' V  z* V)))RENN#@BPS#TU Vs8C%CD 2DD Hooksurfacec t|dt|}|t|ddt|d|t|jt |ddf}||j vrt jd||||y|j j|t jd|||||jd jt|xsd y) uOne WARNING per distinct (hook, callback, error); identical repeats at DEBUG. A callback whose signature names a parameter the hook never sends (``tool_data`` instead of ``tool_name``/``args``) fails identically on every tool call — ~1700 WARNING lines an hour that bury real signals (#111922). The first report names the fields the hook does provide so the plugin author can fix the signature. The key names the callback by module/qualname (not ``id()``, which CPython recycles across plugin reloads) and truncates the message so a hook that embeds tool args in its error cannot grow the set per call; the set is cleared on unload alongside the timeout-suppression map. r#rYrDrZNr%z$%s '%s' callback %s raised again: %szd%s '%s' callback %s raised: %s (%s provides: %s; identical failures are logged at DEBUG from now on)z, z no fields) r)r*r+r#r,_hook_failures_reportedloggerdebugaddwarninglowerrHsorted)rr-r.rqr/rr0keys r1rz(PluginDispatchMixin._report_hook_failures JR9 '"lB7^Ub9cCy!!3s8DS>3 $.. . LL?)Ubdg h  $$((- r Y sGMMOTYYvV\~E^Embm or3c  tdt}|tfgtt j 5j j}jvs|=|tjkDr&tjd||tcdddSjj}|rNt|t k\r._release_token8s(( L//33H=F0044XtD $ 4 4 8 8 II ,!))(3( 0044_dK L L Ls BBB&c jjd<jy#t$r}|d<Yd}~+d}~wwxYw#jwxYw)Nr;r/)runr BaseExceptionset) r/rr.rldonefailurerqoutcomers r1_runnerz?PluginDispatchMixin._run_hook_callback_bounded.._runnerBsc #*;;t/I/I2v#V   ! %!$ %  s' ; AA AAAA/z hermes-hook-(T)targetrdaemonu=Hook '%s' callback %s worker failed to start: %s — skippingruu6Hook '%s' callback %s timed out after %gs — skippingr/r;returnNone)r)r*rFrsobjectr_hook_timeout_suppressed_untilrprtime monotonicrrrrr?_HOOK_MAX_ABANDONED_WORKERSr contextvars copy_context threadingEventThreadstart RuntimeErrorwait!_hook_timeout_suppression_secondsrrr)rr-r.rqrur0suppressed_untilrrthreadr/rrlrrrrrrs` `` @@@@@@@@r1rz.PluginDispatchMixin._run_hook_callback_bounded s JR9 %bf-B_B&9&&AB  $ $ ;#BBFFW D888(49IDNNL\9\56?P% ; ;,,00AIS^/JJ]}gb,HX.Y[^_h[ik%) ; ;* +3377N5:D ( ( 2/ ;2**, "$,. L L  !!m_7UVYWY7Zcgh ! LLNyyy)(( ZNN$t'M'MM33OD //33H=F((33OSUKOOPXY Z NNH)Ubdk m G %. {{7##S ; ;h !   NNO=# /!  ! Z ZsEAJ,>A!J,)-J,?J9-A?K4,J69 K1$K,&K1,K14K=ct|s td|j5|jj |gj t ||dddy#1swYyxYw)z=Add an owner-tagged event subscription in registration order.z*Event subscriber callback must be callableN)callabler _event_lock_subscriptionsrrra)rrbrfrcs r1_subscribe_eventz$PluginDispatchMixin._subscribe_eventesc!HI I    b    * *5" 5 < <=OPUW_=` a b b bs 6A""A+c\d}|j5t|jD]i}|j|}|Dcgc]}|j|k7s|}}|t |t |z z }|r||j|<]|j|=k ddd|Scc}w#1swY|SxYw)aRemove every subscription owned by *owner*; return the count. Queued envelopes re-check membership per callback, so this also cancels already-snapshotted deliveries. TODO(#64229): when the central plugin ownership ledger / registration handles land, route this owner-tagged bookkeeping through that ledger so per-plugin unload cancels event subscriptions alongside every other registration surface. This method is the integration seam. rN)rlistrrbr?)rrbremovedrfentriesentryretaineds r1_remove_plugin_subscriptionsz0PluginDispatchMixin._remove_plugin_subscriptionsls    3d112 3--e4/6Oe%++:NEOO3w<#h-7719D''.++E2 3 3 P 3s",B!BB=B!B!!B+c|j}||jrytj|j|j fdd}||_|j y)Nzhermes-plugin-eventsT)rargsrr) _event_workeris_aliverr_event_worker_loop _event_queuer)rworkers r1_ensure_event_worker_lockedz/PluginDispatchMixin._ensure_event_worker_lockeds\##  &//"3 !!**$2C2C1ELb $ r3c |j} |tur5 |tur|j|j|j y|j ||tur|j|j|j #|tur|j|j|j wxYwr{)rp_EVENT_WORKER_STOP_mark_event_donerk task_done_deliver_event)rdispatch_queuerKs r1rz&PluginDispatchMixin._event_worker_loops!%%'D +--11))$//:((* ##D)11))$//:((*11))$//:((*sBB5C c|j5|jj|d}|dkDr|dz |j|<|jjdddy#1swYyxYw)Nr) _event_idle_event_pending_by_generationrp notify_all)rrkpendings r1rz$PluginDispatchMixin._mark_event_donese    *77;;JJG{@G! 11*=    ' ' )  * * *s AA$$A-c ddlm}|j5|j|jk7r dddy dddt |j dd}|j|j _ |jD]|j5|j|jk7r dddntfd|jj|jgDs dddv dddj} ||jj!j"|fit!j$|j&||j _y#1swY7xYw#1swYxYw#t(t*f$r5}|j-|j||j&|dYd}~Fd}~wwxYw#||j _wxYw)z9Deliver one queued event on the host-owned worker thread.rrNr;c3&K|]}|u ywr{r])rcur subscriptions r1rz5PluginDispatchMixin._deliver_event..sfssl2fsrr)rrrrk_event_generationr) _emit_depthrjr;rirrrprfrcrlcopyrdeepcopyrhrrr)rrKrprevious_depthrcr/rs @r1rz"PluginDispatchMixin._deliver_eventsD    $"8"88  8 !!1!17A>!% 4 $ 2 2 h %%!$*@*@@!!fd>Q>Q>U>UVZV`V`bd>eff !!g ! (00h1/ ))+//XDMM$,,z>PluginDispatchMixin._wait_for_event_dispatch..s 99==j!LPQQr3rN)rrwait_for)rrurks` @r1_wait_for_event_dispatchz,PluginDispatchMixin._wait_for_event_dispatchsP    d//J##,,Q[b-d d d ds -AAc 8t|jdd}|tk\rtj dt|yd}|j 5t |jj|g}|s dddy|j}|jj|d}|tk\r%tj |t| dddyt|t|||dz|tj} |j j#||dz|j|<|j)t+|cdddS#t$j&$r&tj |t|YdddywxYw#1swYyxYw)zQueue *event* without blocking; return the subscriber count scheduled. Pending work is bounded per generation so a blocking subscriber costs one worker and later emits drop.r;ruoEvent bus recursion cap (%d) exceeded while dispatching '%s' — dropping this emit to prevent an infinite loopuUEvent bus pending budget (%d) exhausted while dispatching '%s' — dropping this emitNr)rfrhrirjrkrl)r)r_EVENT_EMIT_DEPTH_CAPrrrtuplerrprr_EVENT_PENDING_CAPrerrrr put_nowaitqueueFullrr?) rrfrhrj budget_msgrirkrrKs r1_dispatch_eventz#PluginDispatchMixin._dispatch_events(('15 ) ) NNEF[]b dl    &!$"5"5"9"9%"DEM  & &//J77;;JJG,,z+=uE & &&T']-W\_`W`%{/G/G/IKD !!,,T2=DaKD - -j 9  , , .}%' & &:: z+=uE! & &  & &s= )F=A F/FE,F.F F F  FFcJt|jj|S)z@Return True when at least one callback is registered for a hook.)r8rrprr-s r1has_hookzPluginDispatchMixin.has_hooksDKKOOI.//r3c Kddlm}|dk7r|jdtg}|}t ||}|t v}|j j|gD]{}t|dt|} |d i|j||} tj| r"|rtj| |n| d{} | |j| }|S7#tj $r5t"j%d|| ||r|jdt&d Yt(t*f$r=} |j-|||| |r|jt/||| Yd} ~ d} ~ wwxYww) u:meth:`invoke_hook` for callers that are already on an event loop. Same payload narrowing, per-callback isolation and result contract. The difference is where an ``async def`` callback runs: here it is awaited on the caller's own loop, so a callback that awaits anything scheduled on that loop can make progress. Through the sync path it runs on a helper thread while the caller blocks in ``done.wait()`` — on the gateway that stalls the whole event loop for the callback's duration. Sync callbacks run inline. Bounded hooks keep ``plugins.hook_callback_timeout`` via ``asyncio.wait_for`` (the coroutine is cancelled, not abandoned); a timed-out ``pre_tool_call`` fails closed. rrrrr#Nz+Hook '%s' callback %s timed out after %.0fsr$r&r])rrrr rvrrrpr)r*rr} isawaitableasyncior r TimeoutErrorrrrrrrr2) rr-rqrrrurrr.r0rr/s r1 ainvoke_hookz PluginDispatchMixin.ainvoke_hooksg F 0 0   8:Q R021)WE #BB ++//)R0 VB#B DH=M VB455b&AB&&s+CN!1!1#w!?TWXC?NN3' V$Y'' iLiYfhopNNgBf#ghz* V)))RENN#@BPS#TU  VsPA4E47A CCCE4CAE1$E4&E142E,&E4,E11E4cLt|jj|dS)z/037J3KKaO $*4+G+G+M+M+O$P = K8} ::23:::?Y[33G[ID| !=gjj$!OPN!#^+.TT@AHW^^:< OO1zz4':J:JSZSaSac d > )K KKUW^WaWa 0 0#d) =- =2r3cdfd } tjrj|n j}t |t s|dt |jy|j}|syt|vst|vr |dyt|jkDr|dt|jy|S#ttf$r}|d|Yd}~yd}~wwxYw)zUEvaluate one section; return its stripped text or None (with a warning) when skipped.cdtjd|zjjg|y)Nz%Plugin system prompt section %s (%s) )rrrFrW)detailrr0s r1_skipz>PluginDispatchMixin._render_prompt_section_text.._skip4s- NN7&@'**gnn e_c er3zraised and was skipped: %sNzreturned %s, not str; skippedz7contained a reserved persistence marker and was skippedz,exceeded max_chars (%d > %d) and was skipped)r6r,rrrr) rrArrr7r,r+r#striprGrIr?rV)r0r,r7r;r/r1s` r1r(z/PluginDispatchMixin._render_prompt_section_text/s  e 4r]r3r1rxrxs-    gg"Jkqoo"*o4BoIVodgo o0V$V$"*V$4BV$MRV$ V$pb(  +*46d&>0$L5 -  0 D*9J 60 r3rx)r-r,r.rr/rrzDict[str, str])r;rrr8)r@r,rAr,rr,)rJrrr,)rqrgrrB)r-r,rur@rr8)Ar[ __future__rrrrr}loggingrrerrr$ dataclassesrtypingrrrrr r r r hermes_cli.middlewarer getLoggerrrr\rr !_HOOK_TIMEOUT_SUPPRESSION_SECONDSrrr2 frozensetSYSTEM_PROMPT_SECTION_POSITIONS'DEFAULT_SYSTEM_PROMPT_SECTION_MAX_CHARSMAX_SYSTEM_PROMPT_SECTION_CHARSr'r)compiler9r>rGrIr<rBrMHERMES_EVENT_NAMESPACErrrrrSr_rare_HOOK_CALLBACK_TIMEOUT_SECS_MAX_HOOK_CALLBACK_TIMEOUT_SECSrrsrvrxr]r3r1rUs #   !KKK9   / 0$)X.=,=='6&787$(!'d$u#,^,<"=*/'"').&)rzz*IJ(=%?;Z M["X $ $ $ $ ! ! !#"'   deer3