PL joBdZddlmZddlZddlZddlmZmZddlm Z m Z ddl m Z ddl mZehdZehd Zed Gd d Zed GddZed GddZd,dZd-dZGddZd.dZd/d Zd0d"Zd1d#Zd2d(Zd3d*Zd4d+ZdS)5a"Pure tool-call loop guardrail primitives. The controller in this module is intentionally side-effect free: it tracks per-turn tool-call observations and returns decisions. Runtime code owns whether those decisions become warning guidance, synthetic tool results, or controlled turn halts. ) annotationsN) dataclassfield)AnyMapping)safe_json_loads)file_mutation_result_landed> read_file web_search web_extract search_filessession_searchbrowser_consolebrowser_snapshotbrowser_get_imagesmcp_filesystem_read_filemcp_filesystem_search_filesmcp_filesystem_get_file_infomcp_filesystem_directory_treemcp_filesystem_list_directorymcp_filesystem_read_text_file"mcp_filesystem_read_multiple_files(mcp_filesystem_list_directory_with_sizes>todopatchmemorycronjobprocessterminal write_file browser_type execute_code send_message skill_manage browser_click browser_press delegate_taskbrowser_scrollbrowser_navigateT)frozenceZdZUdZdZded<dZded<dZded <d Zded <d Z ded <dZ ded<dZ ded<d Z ded<e dZded<e dZded<eddZdS)ToolCallGuardrailConfigaThresholds for per-turn tool-call loop detection. Warnings are enabled by default and never prevent tool execution. Hard stops are explicit opt-in so interactive CLI/TUI sessions get a gentle nudge unless the user enables circuit-breaker behavior in config.yaml. Tboolwarnings_enabledFhard_stop_enabledintexact_failure_warn_afterexact_failure_block_aftersame_tool_failure_warn_aftersame_tool_failure_halt_afterno_progress_warn_afterno_progress_block_afterctSN)IDEMPOTENT_TOOL_NAMES9/home/kuhnn/.hermes/hermes-agent/agent/tool_guardrails.pyz ToolCallGuardrailConfig.PsEZr?)default_factoryzfrozenset[str]idempotent_toolsctSr<)MUTATING_TOOL_NAMESr>r?r@rAz ToolCallGuardrailConfig.QsCVr?mutating_toolsdataMapping[str, Any] | Nonereturn'ToolCallGuardrailConfig'czt|ts |S|d}t|tsi}|d}t|tsi}|}|t|d|jt|d|jt |d|d|jt |d|d|jt |d |d |j t |d|d |j t |d|d |j t |d |d |j S)zABuild config from the `tool_loop_guardrails` config.yaml section. warn_afterhard_stop_afterr.r/ exact_failurer2same_tool_failurer6idempotent_no_progressr9r4r8r:)r.r/r2r6r9r4r8r:) isinstancerget_as_boolr.r/ _positive_intr2r6r9r4r8r:)clsrGrLrMdefaultss r@ from_mappingz$ToolCallGuardrailConfig.from_mappingSs $(( 355LXXl++ *g.. J((#455/733 ! O355s%dhh/A&B&BHD]^^&txx0C'D'DhF`aa%29S0T0TUU1&&*72DHH=[4\4\]]5**$17BZ9[9[\\/$$'4##OTXX>Y5Z5Z[[2''*7##$7B`9a9abb5**%2##$a>abb0%%/    r?N)rGrHrIrJ)__name__ __module__ __qualname____doc__r.__annotations__r/r2r4r6r8r9r:rrCrF classmethodrWr>r?r@r,r,?s"!!!!#####$%%%%%%&&&&&() ))))() ))))"######$$$$$',u=Z=Z'['['[[[[[%*U;V;V%W%W%WNWWWW( ( ( [( ( ( r?r,cHeZdZUdZded<ded<ed d Zdd Zd S)ToolCallSignaturezDStable, non-reversible identity for a tool name plus canonical args.str tool_name args_hashargsrHrI'ToolCallSignature'cXt|pi}||t|S)Nrarb)canonical_tool_args_sha256)rUrarc canonicals r@ from_callzToolCallSignature.from_calls0' 33 sY')2D2DEEEEr?dict[str, str]c |j|jdS)z3Return public metadata without raw argument values.rfrfselfs r@ to_metadatazToolCallSignature.to_metadatas!^$.IIIr?N)rar`rcrHrIrd)rIrk)rXrYrZr[r\r]rjror>r?r@r_r_sjNNNNNNNNFFF[FJJJJJJr?r_ceZdZUdZdZded<dZded<dZded<dZded<d Z d ed <d Z d ed<e ddZ e ddZ ddZd S)ToolGuardrailDecisionz8Decision returned by the tool-call guardrail controller.allowr`actioncodemessagerarr1countNzToolCallSignature | None signaturerIr-c|jdvS)N>warnrrrsrms r@allows_executionz&ToolGuardrailDecision.allows_execution{///r?c|jdvS)N>haltblockr{rms r@ should_haltz!ToolGuardrailDecision.should_haltr}r?dict[str, Any]c|j|j|j|j|jd}|j|j|d<|S)N)rsrtrvrarwrx)rsrtrvrarwrxro)rnrGs r@roz!ToolGuardrailDecision.to_metadatasNkI|Z    > % $ : : < r?r@rqrqsBBFDGIENNNN*.I.... 000X0000X0      r?rqrcMapping[str, Any]rIr`ct|ts$tdt|jt j|dddtS)z5Return sorted compact JSON for parsed tool arguments.z!tool args must be a mapping, got FT,: ensure_ascii sort_keys separatorsdefault)rQr TypeErrortyperXjsondumpsr`rcs r@rgrgs] dG $ $SQDJJi|_i|_i|_d|_dSr<)_exact_failure_counts_same_tool_failure_counts _no_progress_halt_decisionrms r@rz*ToolCallGuardrailController.reset_for_turns(CE"9;&FH<@r?ToolGuardrailDecision | Nonec|jSr<)rrms r@ halt_decisionz)ToolCallGuardrailController.halt_decisions ""r?rar`rcrHrqc $t|t|}|jjst ||S|j|d}||jjkr%t ddd|d|d|||}||_ |S| |rV|j |}|:|\}}||jj kr%t dd d|d |d |||}||_ |St ||S) Nrarxrrrepeated_exact_failure_blockzBlocked z: the same tool call failed zd times with identical arguments. Stop retrying it unchanged; change strategy or explain the blocker.rsrtrvrarwrxidempotent_no_progress_blockz/: this read-only call returned the same result z^ times. Stop repeating it unchanged; use the result already provided or try a different query.) r_rj _coerce_argsrr/rqrrRr4r_is_idempotentrr:) rnrarcrx exact_countdecisionrecord _result_hash repeat_counts r@ before_callz'ToolCallGuardrailController.before_callsz%// <;M;MNN {, S(9 RRR R044YBB $+? ? ?,3>y>>k>>>$!#   H#+D O   y ) ) $&**955F!-3* l4;#FFF4&;XyXX&2XXX#,*"+   H+3D'#O$yINNNNr?)failedrrr bool | Nonec t|}t||}|t||\}}|r,|j|ddz}||j|<|j|d|j|ddz}||j|<|j j r5||j j kr%tddd|d|d|||} | |_ | S|j jr+||j jkrtd d |d |d |||S|j jr+||j jkrtd d |d |d|||St|||S|j|d|j|d||s,|j|dt||St%|} |j|} d} | | d| kr | ddz} | | f|j|<|j jr+| |j jkrtd d|d| d|| |St|| |S)Nrrsame_tool_failure_haltzStopped z : it failed z[ times this turn. Stop retrying the same failing tool path and choose a different approach.rrzrepeated_exact_failure_warningz has failed z times with identical arguments. This looks like a loop; inspect the error and change strategy instead of retrying it unchanged.same_tool_failure_warningzJ times this turn. This looks like a loop; change approach before retrying.)rarwrxridempotent_no_progress_warningz returned the same result z^ times. Use the result already provided or change the query instead of repeating it unchanged.)rr_rjrrrRrpoprrr/r8rqrr.r2r6rrr9) rnrarcrrrx_r same_countr result_hashpreviousrs r@ after_callz&ToolCallGuardrailController.after_callsYD!!%// 4@@ >-i@@IFA 2 f488AFFJK4?D &y 1   ! !)T 2 2 27;;IqIIAMJ8BD *9 5{, t{?g1g1g0!1d9dd*ddd($'   '/#{+  t{?c0c0c,!9$<<+<<<(%'    {+  dk>f0f0f,!4$SS*SSS($'    )9K[deee e "&&y$777 &**9d;;;""9-- S   ! !)T 2 2 2(9 RRR R"6** $((33  HQK;$>$>#A;?L(3\'B)$ ; ' LDK<^,^,^(5 ..L...$"#    %y Xabbbbr?r-c>||jjvrdS||jjvS)NF)rrFrC)rnras r@rz*ToolCallGuardrailController._is_idempotent|s'  2 2 25DK888r?r<)rr)rIr)rIr)rar`rcrHrIrq) rar`rcrHrrrrrIrq)rar`rIr-) rXrYrZr[rrrrrrrr>r?r@rrsMMAAAA ###X#*O*O*O*Od# ]c]c]c]c]c]c~999999r?rrcbtj|j|ddS)zCBuild a synthetic role=tool content string for a blocked tool call.)r guardrailF)r)rrrvro)rs r@toolguard_synthetic_resultrs? :%!--//      r?c |jdvs|js|S|jdkrdnd}d|d|jd|jd|jd }|pd |zS) z;Append runtime guidance to the current tool result content.>rrzrzTool loop hard stopzTool loop warningz [z: z; count=z; rru)rsrvrtrw)rrlabelsuffixs r@append_toolguard_guidancers...h6F. %-_%>%> ! !DWE H H H = H H"*. H H4<4D H H H  LbF ""r?rHc4t|tr|niSr<)rQrrs r@rrsdG,, 444"4r?ct|pd}|? tj|dddt}n##t$rt|}YnwxYw|pd}t |S)NruFTrr)rrrr`rrh)rparsedris r@rrs V\r * *F  $ "% II $ $ $F III $Lb 9  s4AAvaluerrr-c ||St|tr|St|ttfrt|St|tr2|}|dvrdS|dvrdS|S)N>1onyestrueenabledT>0noofffalsedisabledF)rQr-r1floatr`stripr)rrlowereds r@rSrSs }% %#u&&E{{%++--%%'' ; ; ;4 = = =5 Nr?r1cr||S t|}n#ttf$r|cYSwxYw|dkr|n|S)Nr)r1r ValueError)rrrs r@rTrTsY }U z "q[[66g-s ,,cttj|dS)Nzutf-8)hashlibsha256encode hexdigest)rs r@rhrhs* >%,,w// 0 0 : : < <r?r@rs#""""" ((((((((!!!!!!HHHHHH" * i, $< < < < < < < < ~ $ J J J J J J J J  $>        F_9_9_9_9_9_9_9_9D # # # #5555$     ....======r?