epjNUdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZmZddlmZmZddlmZddlmZmZmZmZmZmZddlmZdd lmZ ej!e"Z#d Z$d Z%d Z&d Z'dZ(ddhZ)hdZ*e+Z,de-d<e j.Z/e j0e(Z1de-d<e j.Z2da3de-d<eGddZ4dCdZ5dCd Z6dDdEd%Z7dFd'Z8dGd*Z9dHd.Z:dId1Z;dJd5ZdMd=Z?dFd>Z@dFd?ZAGd@dAe jBZCe jDeCZEdMdBZFdS)Nu Outbound webhook notifications. Reads the ``hooks.outbound:`` list from ``config.yaml`` and registers notify-only callbacks on the existing plugin hook manager, so every ``invoke_hook()`` site can push lifecycle events to external HTTP endpoints — CI systems, dashboards, other agents — with zero changes to call sites and zero polling on the receiving end. This is the outbound mirror of the inbound webhook platform (``gateway/platforms/webhook.py``): inbound wakes Hermes when the world changes; outbound tells the world when Hermes does something. Design notes ------------ * Delivery is fire-and-forget through a bounded in-process queue and a single daemon worker thread. ``invoke_hook()`` runs inside the agent loop, so callbacks must never block on network I/O — they serialize, enqueue, and return ``None`` immediately. Outbound targets can never block a tool call, inject context, or otherwise influence agent flow. * Payloads are signed with HMAC-SHA256 (GitHub-style ``X-Hermes-Signature-256: sha256=`` over the raw body) when a secret is configured. Receivers verify exactly like they verify GitHub webhooks. * No consent prompt: unlike shell hooks, an outbound target executes no code on this machine — it POSTs JSON to a URL the user themselves put in config. ``HERMES_SAFE_MODE=1`` still skips registration, matching plugins / MCP / shell hooks. * Registration is idempotent — safe to invoke from both the CLI entry point and the gateway entry point. Config schema (``~/.hermes/config.yaml``):: hooks: outbound: - url: https://ci.example.com/hermes-events events: [on_session_end, subagent_stop] # secret literal (discouraged) or env var name (preferred): secret_env: HERMES_OUTBOUND_WEBHOOK_SECRET # optional regex, honored for pre/post_tool_call only: matcher: "terminal|delegate_task" timeout: 10 # per-attempt seconds, clamped to [1, 60] name: ci-notify # optional label for logs / `hermes hooks list` Wire format (POST body):: { "hook_event_name": "on_session_end", "tool_name": null, "tool_input": null, "session_id": "sess_abc123", "cwd": "/home/user/project", "extra": {...}, # event-specific kwargs "delivery_id": "3f2c...", # uuid4, unique per POST "timestamp": "2026-07-22T14:00:00Z" } Headers:: Content-Type: application/json User-Agent: Hermes-Agent-Outbound-Webhook X-Hermes-Event: X-Hermes-Delivery: X-Hermes-Signature-256: sha256= # only when secret set ) annotationsN) dataclassfield)datetimetimezone)Path)AnyDictListOptionalSetTuple)error)request <g? pre_tool_callpost_tool_call>args tool_name session_idparent_session_idzSet[Tuple[str, str]] _registered)maxsizez''queue.Queue[Optional[Dict[str, Any]]]'_delivery_queuezOptional[threading.Thread]_workerceZdZUdZded<ded<dZded<dZd ed <dZd ed <eZ d ed <e ddZ ded<ddZ e ddZddZdS) WebhookTargetzDParsed and validated representation of one ``hooks.outbound`` entry.strurlz List[str]eventsnameN Optional[str]secretmatcherinttimeoutF)defaultreprzOptional[re.Pattern]compiled_matcherreturnNonec\t|jtr$|j}|r|nd|_|jrf t j|j|_dS#tj$r3}t d|j|d|_Yd}~dSd}~wwxYwdS)NuLoutbound webhook matcher %r is invalid (%s) — treating as literal equality) isinstancer(r!striprecompiler-rloggerwarning)selfstrippedexcs =/home/thesage/.hermes/hermes-agent/agent/outbound_webhooks.py __post_init__zWebhookTarget.__post_init__|s dlC ( ( :|))++H'/988TDL < - -(* 4<(@(@%%%8 - - -*+/<)-%%%%%%%  - - -sA''B)6(B$$B)c|jp|jSN)r%r")r7s r:labelzWebhookTarget.labelsy$DH$rboolcx|jsdS|dS|j|j|duS||jkS)NTF)r(r- fullmatch)r7rs r: matches_toolzWebhookTarget.matches_toolsN| 4  5  ,(229==TI IDL((r?r.r/)r.r!)rr&r.r@)__name__ __module__ __qualname____doc____annotations__r%r'r(DEFAULT_TIMEOUT_SECONDSr*rr-r;propertyr>rCr?r:r r psNN HHHDNNNN F    !G!!!!*G****-2U4e-L-L-LLLLL - - - -%%%X%))))))r?r cfgOptional[Dict[str, Any]]r.List[WebhookTarget]c t|tsgSddlm}|drtdgS|d}tt|tr|dnd}|sgSddlm }|}g}t5|D]}d }|j D]} | |j f} | tvr|j| gt#| |t| d }td | |j|j|j|r|| dddn #1swxYwY|S) uRegister every configured outbound webhook on the plugin manager. ``cfg`` is the full parsed config dict. Missing, empty, or malformed ``hooks.outbound`` is treated as zero targets — config parsing never raises, because a broken webhook entry must not crash the agent. Returns the targets that ended up wired (deduplicated across repeat calls, so the CLI and gateway can both invoke this safely). r)env_var_enabledHERMES_SAFE_MODEu<HERMES_SAFE_MODE=1 — outbound webhook registration skippedhooksoutboundN)get_plugin_managerFTz?outbound webhook registered: %s -> %s (matcher=%s, timeout=%ds))r1dictutilsrQr5infoget_parse_outbound_blockhermes_cli.pluginsrU_registered_lockr#r"r_hooks setdefaultappend_make_callbackaddr>r(r*) rMrQ hooks_cfgtargetsrUmanager registeredtarget wired_anyeventkeys r:register_from_configrjs c4  %%%%%%)** RSSS   I#%/ 4%@%@J j!!!dG  555555  ""G&(J ** * *FI  fj)+%%))%44;;"5&11$$$  #6<  *!!&)))# ****************( s0CE>>FFct|tsgS|d}tt|tr|dndS)zYParse ``hooks.outbound`` without registering anything. Used by ``hermes hooks list``.rSrTN)r1rVrYrZ)rMrbs r:iter_configured_targetsrlsa c4    I %/ 4%@%@J j!!!d  r?@r*floatr@ctj|z}tj|krntj5tjdkr ddddS dddn #1swxYwYtjdtj|kntj5tjdkcdddS#1swxYwYdS)zBlock until all queued deliveries are done (or *timeout* elapses). Returns ``True`` when the queue fully drained. Test/shutdown helper.rNTg{Gz?)time monotonicrall_tasks_doneunfinished_taskssleep)r*deadlines r:flushrvsd~')H .  X % %  +  /144        4                4 .  X % %  '55/14555555555555555555s#A&&A*-A*(CC  C r/ct5tdddn #1swxYwY tt3#t j$rYdSwxYw)zAClear the idempotence set and drain the queue. Test-only helper.N)r\rclearr get_nowait task_donequeueEmptyrLr?r:reset_for_testsr}s   (  & & ( ( (  % % ' ' ' ( ;     s.224A..BBrawr c|gSt|ts/tdt |jgSg}t |D],\}}t||}|||-|S)Nz8hooks.outbound must be a list of webhook targets; got %s) r1listr5r6typerE enumerate_parse_single_targetr_)r~rcientryrfs r:rZrZs { c4  F II     #%GcNN##5%a//   NN6 " " " Nr?indexr)Optional[WebhookTarget]c :ddlm}t|ts0td|t |jdS|d}t|tr| std|dS| }| dstd||dS| drtd ||d }t|tr|s>td |d t|dSg}|D]Y}||vr||td ||d t|Z|std|dS|d}|2t|tstd|d}|7t#d|Dstd||d}|dt$} t'|} n@#t(t*f$r,td||t$t$} YnwxYwt-dt/| t0} t3||} |d} t| tsd} t5||| | || S)Nr) VALID_HOOKSzIhooks.outbound[%d] must be a mapping with 'url' and 'events' keys; got %sr"z/hooks.outbound[%d] is missing a non-empty 'url')http://zhttps://u:hooks.outbound[%d].url must be http(s); got %r — skippedruphooks.outbound[%d].url uses plain http:// — payloads (including tool inputs) travel unencrypted. Prefer https.r#z>hooks.outbound[%d] needs a non-empty 'events' list (valid: %s)z, z8hooks.outbound[%d]: unknown event %r ignored (valid: %s)u2hooks.outbound[%d] has no valid events — skippedr(z;hooks.outbound[%d].matcher must be a string regex; ignoringc3(K|] }|tvVdSr=)_TOOL_SCOPED_EVENTS).0es r: z'_parse_single_target..Ds(&P&PAq,?'?&P&P&P&P&P&Pr?umhooks.outbound[%d].matcher=%r will be ignored — matcher is only honored for pre_tool_call / post_tool_call.r*zEhooks.outbound[%d].timeout must be an int (got %r); using default %dsr%r$)r"r#r%r'r(r*)r[rr1rVr5r6rrErYr!r2lower startswithrjoinsortedr_anyrJr) TypeError ValueErrormaxminMAX_TIMEOUT_SECONDS_resolve_secretr ) rr~rr" events_rawr#evr( timeout_rawr*r'r%s r:rr s...... c4  !499#5   t ''%..C c3  syy{{H%PPPt ))++C 99;; ! !"9 : : H 3   t yy{{i((  =>C   ""J j$ ' 'z L 499VK0011   tF    MM"     NNJr499VK%8%899      @%   tggi  G:gs#;#; I    3&P&P&P&P&P#P#P :;@'   '')%<==K*k"" z "***  +/F   * * !S"56677G UC ( (F 776??D dC    ZZ\\    sK:LLDict[str, Any]r&c|d}t|trz|rftj|d}|r|St d||dS|d}t|tr|r|SdS)zE``secret_env`` (env var name, preferred) wins over inline ``secret``. secret_envr$u^hooks.outbound[%d].secret_env=%r is not set in the environment — deliveries will be UNSIGNEDNr')rYr1r!r2osenvironr5r6)rr~rvaluer's r:rrfs&&J*c""z'7'7'9'9 z//11266  L ./4j6F6F6H6H   t WWX  F&#6 4r?rhr!rfcVd fd }ddjd|_|j|_|S) zABuild the notify-only closure ``invoke_hook()`` calls per firing.kwargsr r.r/cjtvr*|dsdStjj} t ||}n4#t$r't dj dYdSwxYwtt||dS)NrzBoutbound webhook payload serialization failed (event=%s target=%s)Texc_info) rrCrYuuiduuid4hex_serialize_payload Exceptionr5r6r>_enqueue_build_delivery)r delivery_idbodyrhrfs r: _callbackz!_make_callback.._callbacks ' ' '&&vzz+'>'>?? tjll&  %eV[AADD    NN#V\D    44   kBBCCCtsA -BBzoutbound_webhook[:])rr r.r/)r>rErG)rhrfrs`` r:r`r`|sX EUDDV\DDDI&/I r?rrbytesc d|D} ttj}n#t$rd}YnwxYw||dt |dtr|dnd|dp|dpd|||tj tj  d d d }tj|d t dS)ueRender the POST body. Same top-level shape as shell hooks' stdin (documented in :mod:`agent.shell_hooks`), plus delivery metadata. ``delivery_id`` is shared with the ``X-Hermes-Delivery`` header so receivers can dedupe on either — and since it (plus ``timestamp``) lives inside the HMAC-signed body, it doubles as replay protection. c,i|]\}}|tv||SrL)_TOP_LEVEL_PAYLOAD_KEYS)rkvs r: z&_serialize_payload..s) R R Rtq!:Q1Q1Qa1Q1Q1Qr?r$rrNrr)tzz+00:00Z)hook_event_namer tool_inputrcwdextrar timestampF) ensure_asciir+utf-8)itemsr!rrOSErrorrYr1rVrnowrutc isoformatreplacejsondumpsencode)rhrrextrasrpayloads r:rrs-S Rv||~~ R R RF$(**oo !ZZ ,,,6vzz&7I7I4,P,PZfjj(((VZjj..W&**=P2Q2QWUW"\X\222  3    G :gE3 ? ? ? F Fw O OOs A AArcdd||d}|jrRtj|jd|tj}d||d<|j|j||||j dS)Nzapplication/jsonzHermes-Agent-Outbound-Webhook)z Content-Typez User-AgentzX-Hermes-EventzX-Hermes-Deliveryrzsha256=zX-Hermes-Signature-256)r"r>rhrheadersr*) r'hmacnewrhashlibsha256 hexdigestr"r>r*)rhrfrrrdigests r:rrs+5( G }? M  ) )4  )++ -?f,>,>()z>   r?deliveryct t|dS#tj$r2t dt|d|dYdSwxYw)NuEoutbound webhook queue full (%d pending) — dropping %s event for %srhr>)_ensure_workerr put_nowaitr{Fullr5r6QUEUE_MAX_SIZErs r:rrs ""8,,,,, :    $hw&7'9J       s,=A-,A-cttrdSt5t'tr ddddStjt ddattjtdddddS#1swxYwYdS)Nzoutbound-webhooksT)rfr%daemonrmr*) ris_alive _worker_lock threadingThread _worker_loopstartatexitregisterrvrLr?r:rrsw//11  , ,  7#3#3#5#5   , , , , , , , ,"&9$      s++++ , , , , , , , , , , , , , , , , , ,s"B6AB66B:=B:c| t} |t|nW#t$rJtdt |tr|dnddYnwxYwtn#twxYw)NTz-outbound webhook delivery crashed (target=%s)r>?r) rrY_deliverrr5r6r1rVrzrs r:rrs ("&&(( (#"""    NN?)3Hd)C)CL W%%%         % % ' ' ' 'O % % ' ' ' ' (s'.BAB?BBBB:ceZdZdZdZdS)_NoRedirectHandleruDRefuse to follow redirects. urllib's default handler converts a redirected POST into a body-less GET — the signed payload would be silently dropped and the headers re-sent to a location the user never configured. Treat any 3xx as a delivery failure instead (surfaced as HTTPError by returning None). cdSr=rL)r7reqfpcodemsgrnewurls r:redirect_requestz#_NoRedirectHandler.redirect_requeststr?N)rErFrGrHrrLr?r:rrs-r?rc ^d}tdtdzD]}tj|d|d|dd} t||d 5}t |d d }d d d n #1swxYwYd |cxkrd kr/nn,td|d|d|d Sd|}n#tj $r}d|j }d |j cxkrdkrMnnJt d|d|d||j ddYd }~d Sd|j cxkrdkr3nn0t d|d|d|Yd }~d SYd }~n=d }~wt$r-}t!|pt#|j}Yd }~nd }~wwxYw|tkrt'jt*|zt dt|d|d|d S)uPOST with bounded retries. Retries on connection errors and 5xx; 4xx is the receiver telling us the request itself is wrong — no retry. 3xx redirects are never followed (misconfiguration — fix the URL).r$rr"rrPOST)datarmethodr*rstatusNi,z.outbound webhook delivered: %s -> %s (HTTP %d)rhr>zHTTP iu{outbound webhook target redirected (event=%s target=%s): %s -> %s — redirects are not followed; update the configured urlLocationriuCoutbound webhook rejected (event=%s target=%s): %s — not retryingzMoutbound webhook delivery failed after %d attempt(s) (event=%s target=%s): %s)rangeMAX_DELIVERY_ATTEMPTS urlrequestRequest_openeropengetattrr5debugurlerror HTTPErrorrr6rrYrr!rrErprtRETRY_BACKOFF_SECONDS)r last_errorattemptrresprr9s r:rrsJ1A566&8&8 UO&!Y'      8c8I+>?? 64 x55 6 6 6 6 6 6 6 6 6 6 6 6 6 6 6f""""s""""" DW%x'8&)))JJ!   +++Jch$$$$$$$$$%&.w&7'9J  C @ @  ch$$$$$$$$$#$,W$5x7H  8 8 8S7T#YY%7JJJJJJ 8 * * * J,w6 7 7 7 NN x0(72CZsU "C+B = C B CB F G%#G  G)rMrNr.rO)rm)r*rnr.r@rD)r~r r.rO)rr)r~r r.r)rr)r~rr.r&)rhr!rfr )rhr!rrrr!r.r) rhr!rfr rrrr!r.r)rrr.r/)GrH __future__rrrrrloggingrr{r3rrpr dataclassesrrrrpathlibrtypingr r r r r rurllibrrrr getLoggerrEr5rJrrrrrrsetrrILockr\Queuerrrr rjrlrvr}rZrrr`rrrrrHTTPRedirectHandlerr build_openerrrrLr?r:rs@@@D#"""""    ((((((((''''''''8888888888888888$$$$$$((((((  8 $ $'(89SRR%(CEE ))))!9>##;F5; <<<y~ &***** $)$)$)$)$)$)$) $)V3333l 5 5 5 5 5     $WWWWt,0PPPP<0    ,,,,& ( ( ( (     7    "* !"4 5 5111111r?