+ lHjZ7a0t$Rt^RIHt^RIt^RIt^RIt^RIt^RIH t H t ^RI H t H t HtHt]P !]4t] !RR44t]P(!4t/tR]R&/tR ]R &/tR ]R &R tRtRtRtRtRtRt RaGateway-side clarify primitive (blocking event-based queue). The agent runs on a worker thread while the event loop handles the user's reply, so a pending clarify is stored module-level (same shape as ``tools.approval``) and the agent thread blocks on an ``Event`` until an adapter button callback or the gateway text-intercept resolves it, or the timeout fires. Adapters render inline buttons (an "Other" row flips the entry into text-capture mode) or a numbered-list text fallback.) annotationsN) dataclassfield)CallableDictListOptionalc]tRt^t$RtR]R&R]R&R]R&R]R&RtR ]R &]!]PR 7t R ]R &Rt R]R&Rt R ]R&Rt R#) _ClarifyEntryz5One pending clarify request inside a gateway session.str clarify_id session_keyquestionOptional[list[str]]choicesFbool multi_select)default_factoryzthreading.EventeventN Optional[str]response awaiting_text)__name__ __module__ __qualname____firstlineno____doc____annotations__rr threadingEventrrr__static_attributes__r:/home/ubuntu/.hermes/hermes-agent/tools/clarify_gateway.pyr r sL?OM  L$"9??CE?C"Hm"M4r"r zdict[str, _ClarifyEntry]_entrieszdict[str, list[str]]_session_indexz*dict[str, Callable[[_ClarifyEntry], None]] _notify_cbsresolvedrejected_proserejected_selection no_pendingskipzskippedz cancelledFc 0V^8dQhRRRRRRRRRRR R /#) r r r rrrrrreturnr r)formats"r# __annotate__r01s9   3 # H[  ,9 r"c P\YY#'d \V4MR\V4;'d \V4\V4'*R7p\;_uu_4V\V&\ P V.4PV4RRR4V# +'giT#;i)zRegister a pending clarify request; caller then blocks on ``wait_for_response``. Open-ended (no choices) entries start in text mode: the next message IS the response.N)r)r listr_lockr$r% setdefaultappend)r r rrrentrys&&&&& r#registerr71s *8gT'][_|,>>gRVW^R_N_ aE $!!+r299*E  L  Ls /B B% c$V^8dQhRRRRRR/#)r-r r timeoutfloatr.rr)r/s"r#r0r0=s!''#''-'r"c\;_uu_4\PV4pRRR4XfR#^RIHp^RIHpVe\V4R8:dRM$\P!4\V4,pR\P!4R\P!4/pVfRMV\P!4, pV^8:g-VPP\RV4R7'dMaV!4'dD\;_uu_4VPP4'g \VnRRR4MVfKV!VR 4K\;_uu_4\P#VR4VPP%4\&PVP(4;'g.pW9d:VP+V4V'g!\&P#VP(R4RRR4VP # +'giEL;i \ dRpELi;i +'giEL;i +'giTP #;i) zBlock until the entry resolves or ``timeout`` (``<= 0`` = unlimited) elapses; None on timeout/unknown id. Polls in 1s slices so the inactivity heartbeat keeps firing (a single long ``Event.wait`` would let the gateway watchdog kill a live prompt).N)touch_activity_if_due)is_interruptedg last_touchstartg?)r9z!waiting for user clarify response)r3r$gettools.environments.baser< Exceptiontools.interruptr=r:time monotonicrwaitminis_set CANCELLEDrpopsetr%r remove) r r9r6r<r=deadlineactivity_state remainingidss && r#wait_for_responserQ=s  Z(  }%A/%.C*?tT^^EUX]^eXfEfH"DNN$4gt~~?OPN #+CDNNU[[--c#y6I-JJ    {{))++%.EN  ! , !.2U V  Z&   !2!2399r   JJz """5#4#4d;  >>G  % $%  >>s;HH.,I-A8I& I H+ . H?>H? I  I1 c$V^8dQhRRRRRR/#)r-r r rr.rr)r/s"r#r0r0gs!str"cF\;_uu_4\PV4pVe!VPP 4'd RRR4R#Ve \ V4MRVnVPP4RRR4R# +'giR#;i)zPUnblock the waiter on ``clarify_id``; False if already resolved/expired/unknown.NFT)r3r$r@rrHr rrK)r rr6s&& r#resolve_gateway_clarifyrUgsg  Z( =EKK..00 +3*>XB  s9B B1B B c V^8dQhRRRR/#)r-r r r.Optional[_ClarifyEntry]r)r/s"r#r0r0rsQQCQ$;Qr"c\;_uu_4\PV4pVe#VPP 4'gTMRuuRRR4# +'giR#;i)aTThe entry for ``clarify_id`` while it is still awaiting an answer, else None (unknown, answered, timed out or cleared). Read-only: adapters rendering native choice cards compare it by identity with the entry they rendered and read ``session_key`` / ``choices`` / ``multi_select`` from it; answering goes through ``resolve_gateway_clarify``.N)r3r$r@rrHr r6s& r# get_pendingrZrs?  Z()%++2D2D2F2FuD s9A A A( include_choice_promptsc$V^8dQhRRRRRR/#)r-r r r[rr.rWr)r/s"r#r0r0|s"    Zq r"c0\;_uu_4\PV4;'g.FFp\PV4pVfKV'gVP'gK:VuuuRRR4# RRR4R# +'giR#;i)zOldest pending entry awaiting free text (open-ended, or after "Other"); ``include_choice_prompts=True`` returns the oldest unresolved entry of any kind (user typed at an active choice prompt: resolve it rather than queue a follow-up turn).N)r3r%r@r$r)r r[cidr6s&$ r#get_pending_for_sessionr_|sf !%%k288b8CLL%E &<@S@S@S 8 s#9B BB)B7B B c$V^8dQhRRRRRR/#)r-textr rz list[str]r.rr)r/s"r#r0r0s!sY=r"c^RIHpV!V4P4pVFBpV!\V44P4V8XgK)\V4P 4u# R#)zStripped choice text matching ``text`` case-insensitively, ignoring the '(Recommended)' suffix the first choice carries by the time it reaches adapters; None if no match.)strip_recommendedN)tools.clarify_toolrccasefoldr strip)rarrcwantedchoices&& r# _match_labelrisV5 t $ - - /F S[ ) 2 2 4 >v;$$& & r"c V^8dQhRRRR/#)r-rar r.rr)r/s"r#r0r0sQQQ 3Qr"cbRV9dGVPR4Uu.uF*qP4'gKVP4NK, up#VP4p\V4^8d=\;QJdRV4F 'dK RM RM !RV44'dV#R#uupi)zQComma-separated tokens, or space-separated all-numeric tokens ("1 3"); else None.,c3@"TFqP4xK R#5iN)isdigit).0ps& r# _split_tokens..s*F199;;sFTN)splitrflenall)ratpartss& r# _split_tokensrysz d{#'::c?@?aggi  ?@@ JJLEJNss*F*Fsss*F*F'F'F5PDPAs B,B,c V^8dQhRRRR/#)r-rar r.rr)r/s"r#r0r0s#$r"cB\V4R# \dR#i;i)TF)int ValueError)ras&r#_is_intr~s# D  s  c$V^8dQhRRRRRR/#)r-rar rrr.r)r/s"r#r0r0s(__C_2E_Qd_r"ca\V4P4pV'gR#\V4pVf>VPR4pVP 4'g\ V4'dV.#R#RV9g V'g T;'gR#\ ^\ RT;'g.4^R74o\;QJdV3RlV4F 'dK RM RM!V3RlV44'dV#R#) zTokens when ``text`` looks like a typed selection (bare int, comma list, all-numeric space list); None for free prose so the gateway can release the clarify. Comma-list labels may span up to the longest choice's word count.N-rlc3f"TF'p\\V4P44xK) R#5irn)rur rt)rpcs& r#rr,_selection_attempt_tokens..s"GACA //s/1)defaultc3<"TF8qP4;'g\VP44S8*xK: R#5irn)rorurt)rprw max_wordss& r#rrrs/TVCCAGGI)(CCVs A%AFT)r rfry removeprefixror~maxrv)rarstrippedtokensdigitsrs&& @r#_selection_attempt_tokensrs4y H  8 $F ~&&s+#^^--1B1BzLL (&~~AsGBGQRSTISTVTSSSTVTTT6^Z^^r"c$V^8dQhRRRRRR/#)r-r6r rr r.rr)r/s"r#r0r0s!>>>#>->r"c&\W4^,#)z;Accepted value for a typed reply, or None on any rejection.)_coerce_text_response_detailed)r6rs&&r#_coerce_text_responsers )% :1 ==r"c$V^8dQhRRRRRR/#)r-r6r rr r.z#tuple[Optional[str], Optional[str]]r)r/s"r#r0r0s'FF-F3FKnFr"cz\V4P4pVP4\8HpVP'gV'd \ R3#TR3#VP 'd$\W4p\W P4RJpMt\V4pV'd\V4^, MRp^Tu;8:d\VP48dMMVPV,M\W P4pVeVR3#V'd \ R3#VP'dVR3#RV'dR3#R3#)u#Map a typed reply to ``(value, None)`` or ``(None, reason)``: ``"invalid_selection"`` (selection-shaped but out of range/unrecognised — keep the clarify armed for a retry) or ``"prose"`` (free text on a native choice prompt — the gateway may cancel and route normally so a redirect-to-steer path cannot deadlock behind the waiting tool). Open-ended entries and ``awaiting_text`` accept any text; numeric picks and exact labels always resolve; multi-select returns a JSON array string (decoded tool-side); one bad token rejects the whole reply.Ninvalid_selectionprose)r rfre SKIP_WORDrSKIPPEDr_coerce_multi_select_textrr~r|rurir)r6rrais_skipcoercedselection_shapedidxs&& r#rrs  x=   Dmmo*G ==="t33t33 +E84T==IQUU#4=/c$i!mR()S(E3u}}3E(E%--$$v5 ==??e*q.C12c1HCL1HC %++-dE 0E =  OOE "68@4::hU 3ITIr"c$V^8dQhRRRRRR/#)r-r r rr.r)r/s"r#r0r0s!  3 # # r"c\VRR7pVf\#\W!4wr4VfVR8Xd\#\#\ VP V4'd\#\#)zTTry to resolve the oldest pending clarify from typed text; returns a TEXT_* outcome.T)r[r)r_TEXT_NO_PENDINGrTEXT_REJECTED_SELECTIONTEXT_REJECTED_PROSErUr TEXT_RESOLVED)r rr6rreasons&& r#!attempt_text_response_for_sessionrs^ #K ME }4UEOG*04G*G&`M``u//99 r"c$V^8dQhRRRRRR/#)r-r r rr.rr)r/s"r#r0r0s&UU3U#U$Ur"c&\W4\8H#)zETrue only when the typed reply was accepted and the waiter unblocked.)rr)r rs&&r#!resolve_text_response_for_sessionrs ,[ C} TTr"c V^8dQhRRRR/#)r-r r r.rr)r/s"r#r0r0s!!3!4!r"c\;_uu_4\PV4pVeRVnVRJuuRRR4# +'giR#;i)zMFlip an entry into text-capture mode (user picked 'Other'); False if unknown.NT)r3r$r@rrYs& r#mark_awaiting_textrs7  Z(  "&E D s $> A c V^8dQhRRRR/#)r-r r r.rr)r/s"r#r0r0sccScTcr"c8\;_uu_4\;QJd9R\PV4;'g.4F 'gK RM. RM*!R\PV4;'g.44uuRRR4# +'giR#;i)z>True when this session has at least one pending clarify entry.c3P"TFp\PV4RJxK R#5irn)r$r@rpr^s& r#rrhas_pending..s b.s i9h#hll3--9hs#%N) r3r2r%rJrrHrIrrK)r cancelledr6s& r# clear_sessionr s  in>P>PQ\^`>a>g>geg9hiE} 2 2 4 4&EN KKOO  NI j    sAB')4B'' B8 c V^8dQhRRRR/#)r-configdictr.r|r)r/s"r#r0r0s  D S r"cVPR4;'g/PR4pVf,VPR4;'g/PRR4p\V4# \\3dR#i;i)uClarify timeout (seconds): legacy ``clarify.timeout`` if explicitly set, else ``agent.clarify_timeout``, else 3600 — the single source of truth for every surface (gateway, CLI, TUI). ``<= 0`` is kept verbatim (unlimited); non-numeric -> 3600.clarifyr9agentclarify_timeout)r@r| TypeErrorr})rraws& r#resolve_clarify_timeoutrss ::i & &B + +I 6C {zz'"((b--.?F3x z "s A&&A;:A;cV^8dQhRR/#)r-r.r|r)r/s"r#r0r0(s  S r"ch^RIHp\V!4;'g/4# \dR#i;i)aClarify timeout from config.yaml; 0/negative = unlimited. Default 3600: long enough that a user who stepped away still finds a live entry when they tap, short enough that an abandoned prompt eventually unblocks the agent thread instead of pinning the guard. The old 600s default evicted the entry mid-think, so a late tap landed on a dead entry and the agent hung on ``running: clarify`` (#32762).  load_configr)hermes_cli.configrrrBrs r#get_clarify_timeoutr(s11&{}':':;; s"" 11)Frn)4__conditional_annotations__r __future__rrloggingrrD dataclassesrrtypingrrrr getLoggerrloggerr RLockr3r$rr%r&rrrrrrrIr7rQrUrZr_riryr~rrrrrrrrrrr)rs@r#rs+#  (11   8 $        %' "'')$):< 7< &.     'TQ PU Q_"> F8J( U !c "  r"