yjClUdZddlmZddlZddlZddlZddlmZmZddl m Z m Z m Z m Z ejeZeGddZejZiZded <iZd ed < d7d8dZd9dZd:dZd dd;d Zdd%Zd?d&Zd@d'ZdAd)Z dBd,Z!dCd-Z"iZ#d.ed/<dDd3Z$dEd4Z%dFd6Z&dS)GuGateway-side clarify primitive (blocking event-based queue). The ``clarify`` tool needs to ask the user a question and block the agent thread until they respond. In CLI mode this is trivial — ``input()`` is synchronous. In gateway mode the agent runs on a worker thread while the event loop handles the user's reply, so we need a thread-safe primitive that: * stores a pending clarify request (with a generated ``clarify_id``), * blocks the agent thread on an ``Event``, * resolves the wait when the gateway's button-callback or text-intercept fires ``resolve_gateway_clarify(clarify_id, response)``, * supports timeouts so a user who never responds does NOT hang the agent thread forever (which would also pin the gateway's running-agent guard). State is module-level (same shape as ``tools.approval``) so platform adapters can call ``resolve_gateway_clarify`` without holding a back- reference to the ``GatewayRunner`` instance. Two delivery paths from the adapter: 1. **Button UI** — adapters override ``send_clarify`` to render inline buttons (e.g. Telegram ``InlineKeyboardMarkup``). The button callback resolves with the chosen string. A final "Other (type answer)" button enters text-capture mode for free-form responses. 2. **Text fallback** — adapters without rich UI render a numbered list. The user replies with a number ("2") or with free text; the gateway's ``_handle_message`` intercepts the reply and resolves directly. ) annotationsN) dataclassfield)CallableDictListOptionalceZdZUdZded<ded<ded<ded<dZd ed <eej Z d ed <dZ ded<dZ d ed<ddZ dS) _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_textreturnDict[str, object]c|j|j|j|jrt |jndt |jdS)N)r rrrr)r rrrlistrr)selfs ;/home/ragecks/.hermes/hermes-agent/tools/clarify_gateway.py signaturez_ClarifyEntry.signature;sH/+ -1\CtDL)))t !233    )rr) __name__ __module__ __qualname____doc____annotations__rr threadingEventrrrrr rr r /s??OOOMMM    L"U9?CCCECCCC"H""""M      r r zDict[str, _ClarifyEntry]_entrieszDict[str, List[str]]_session_indexFr r rrrrrrrc Tt||||rt|ndt|ot|t| }t5|t|<t |g|dddn #1swxYwY|S)zRegister a pending clarify request and return the entry. The caller (gateway clarify_callback) will then send the prompt to the user and block on ``wait_for_response(clarify_id, timeout)``. N)r rrrrr)r rr_lockr)r* setdefaultappend)r rrrrentrys rregisterr0Ps !(2W d,''9DMMw--'   E FF$!!+r2299*EEEFFFFFFFFFFFFFFF Ls9BB!$B!timeoutfloatrcpt5t|}dddn #1swxYwY|dS ddlm}n#t $rd}YnwxYw|dupt |dk}|rdn"tjt |z}tjtjd} |d}n-|tjz }|dkrn;td|}|j |rn| ||d ]t5t |dt|j} | r;|| vr7| || s t |jddddn #1swxYwY|jS) uHBlock on the entry's event until resolved or timeout fires. Polls in 1-second slices so the agent's inactivity heartbeat keeps firing — without this, ``Event.wait(timeout=600)`` blocks the thread for 10 minutes with zero activity touches and the gateway's inactivity watchdog kills the agent while the user is still typing. ``timeout <= 0`` means an unlimited wait (never auto-skip mid-think); the heartbeat still fires each slice so inactivity watchdogs don't kill a live prompt. Returns the resolved response string, or ``None`` on timeout. Nr)touch_activity_if_dueg) last_touchstartTg?)r1z!waiting for user clarify response)r,r)gettools.environments.baser4 Exceptionr2time monotonicminrwaitpopr*rremover) r r1r/r4 unlimiteddeadlineactivity_stateslice_s remainingidss rwait_for_responserFksh )) Z(())))))))))))))) }t%AAAAAAA %%% $%485>>S#8I Gttdn&6&6w&GH$(N$4$4t~?O?OPPN W  GG 4>#3#33IA~~#y))G ;  G  , ,   , ! !.2U V V V W << Z&&&  !233  <:$$ JJz " " " <""5#4d;;;<<<<<<<<<<<<<<< >s0/33A AA"A8F&&F*-F*rct5t|}| ddddS dddn #1swxYwY|t|nd|_|jdS)zUnblock the agent thread waiting on ``clarify_id``. Returns True if an entry was found and resolved, False otherwise (already resolved, expired, or never existed). NFT)r,r)r7r rrset)r rr/s rresolve_gateway_clarifyrJs  Z(( = '/&:S]]]EN KOO 4sAAAinclude_choice_promptsrLOptional[_ClarifyEntry]ct5t|pg}|D]8}t|}||s|jr|ccdddS9 ddddS#1swxYwYdS)aReturn the oldest pending clarify entry for a session, or None. By default this only returns entries awaiting free-form text (open-ended clarifies, or a multi-choice clarify after the user picked ``Other``). Gateways may pass ``include_choice_prompts=True`` when the user has typed directly in response to an active multi-choice prompt; in that case the oldest unresolved clarify is returned so the text can resolve it instead of being queued as an unrelated follow-up turn. N)r,r*r7r)r)rrLrEcidr/s rget_pending_for_sessionrPs   --3  CLL%%E}% )<    sA A.A..A25A2r/cNt|}|js|S|jrt ||}||S|jr|ndS t |dz }n#t$rd}YnwxYwd|cxkrt|jkrnn |j|S|jD]n}| t| kr#t|cSo|jr|SdS)uMap typed choice replies to canonical choice text, otherwise keep or reject custom text. For native interactive multi-choice clarifies (button UI, awaiting_text=False): - Accept numeric selections ("2" → choice[1]) - Accept exact choice label matches (case-insensitive) - Reject arbitrary prose (return None) so the message continues as a normal turn For multi-select clarifies (entry.multi_select=True): - Accept several numbers separated by commas and/or spaces ("1,3" / "1 3") - Accept exact choice label matches (single or comma-separated) - Out-of-range numbers reject the whole reply (return None) so the user can retry instead of silently getting a partial selection - Selections are returned as a JSON array string, which the clarify tool's ``_parse_multi_select_response`` decodes back into a list For text fallback or awaiting_text mode: - Accept any text (numeric/label/custom) after passing through coercion For open-ended clarifies (no choices): - Accept any text Returns None when the response should be rejected (arbitrary prose for native multi-choice). Nr) r striprr_coerce_multi_select_textrint ValueErrorlencasefold)r/rtextcoercedidxchoices r_coerce_text_responser^sV0 x==   D =  5+E488  N*4tt4$ii!m  C$$$$#em$$$$$$$}S!!-'' ==??c&kk//11::<< < <v;;$$&& & & & =   4sA%% A43A4rZcddl}|sdS|jpg}d|vr d|dD}nP|}t|dkr&t d|Dr d|D}n|g}g}|D]}|rst |dz }d|cxkrt|krDnnAt||} | |vr| | dSd} |D]n} | t|  kr#t| } no| dS| |vr| | |sdS| |d S) aParse a typed multi-select reply into a JSON array of choice labels. Accepts numbers and/or exact labels separated by commas (and, for all-numeric replies, bare spaces): "1,3", "1 3", "staging, prod". Returns ``None`` when any token is out of range or unrecognised so the caller can reject the reply cleanly instead of resolving a partial or wrong selection. rN,c^g|]*}||+Sr(rT).0ts r z-_coerce_multi_select_text..s-BBB B!''))BBBr rRc3bK|]*}|V+dSN)rTisdigitrcps r z,_coerce_multi_select_text..s6!E!E!!''))"3"3"5"5!E!E!E!E!E!Er c6g|]}|Sr(rbris rrez-_coerce_multi_select_text..s ///Aaggii///r F) ensure_ascii) jsonrsplitrXallrhrVr rTr.rYdumps) r/rZ_jsonrtokenspartsselectedtokenr\labelmatchedr]s rrUrUs tm!rG d{{BBTZZ__BBB  u::>>c!E!Eu!E!E!EEE>/////FFVFH%% ==?? e**q.CC&&&&#g,,&&&&&GCL))//11((OOE***44  F~~3v;;#4#4#6#6#?#?#A#AAAf++++--B ?44 ( " " OOG $ $ $ t ;;xe; 4 44r c~t|d}|dSt||}|dSt|j|S)zResolve the oldest pending clarify in ``session_key`` from typed text. Returns False if no pending clarify exists or if the response was rejected (arbitrary prose for native interactive multi-choice clarifies). TrKNF)rPr^rJr )rrr/r[s r!resolve_text_response_for_sessionrz<sT $K M M ME }u#E844Gu "   r ct5t|}| ddddSd|_ ddddS#1swxYwYdS)zFlip an entry into text-capture mode (user picked the 'Other' button). Returns True if the entry exists and was flipped, False otherwise. NFT)r,r)r7r)r r/s rmark_awaiting_textr|Qs  Z(( =# sAAA A ct5t|pg}td|DcdddS#1swxYwYdS)zEReturn True when this session has at least one pending clarify entry.c3NK|] }t|duV!dSrg)r)r7rcrOs rrkzhas_pending..bs3@@S8<<$$D0@@@@@@r N)r,r*r7any)rrEs r has_pendingr^s AA  --3@@C@@@@@AAAAAAAAAAAAAAAAAAs5A  AArVct5tt|gpg}d|D}dddn #1swxYwYd}|D]*}|d|_|j|dz }+|S)aResolve and drop every pending clarify for a session. Used by session-boundary cleanup (e.g. ``/new``, gateway shutdown, cached-agent eviction) so blocked agent threads don't hang past the end of their session. Returns the number of entries cancelled. cDg|]}t|dSrg)r)r>rs rrez!clear_session..ns&:::s8<<T**:::r NrrHrR)r,rr*r>rrrI)rrEentries cancelledr/s r clear_sessionres ;;>%%k266<"==::c:::;;;;;;;;;;;;;;;I   =   Q s7A  AAconfigdictc|dpid}|+|dpidd} t|S#ttf$rYdSwxYw)acResolve the clarify timeout (seconds) from an already-loaded config dict. Single source of truth shared by every surface (messaging gateway, CLI, TUI/desktop) so the timeout can't drift between them. Resolution order: 1. legacy top-level ``clarify.timeout`` if a user explicitly set it, 2. else the canonical ``agent.clarify_timeout``, 3. else 3600 (1 hour). ``<= 0`` is preserved verbatim and means *unlimited* to callers (never auto-skip while the user is still deciding); the waiting loops translate that into a null deadline. A non-numeric value falls back to 3600. clarifyr1Nagentclarify_timeout)r7rV TypeErrorrW)rraws rresolve_clarify_timeoutrs ::i &B + +I 6 6C {zz'""(b--.?FF3xx z "ttsA((A=<A=cd ddlm}t|piS#t$rYdSwxYw)uRead the clarify response timeout (seconds) from config. Defaults to 3600 (1 hour) — long enough that a user who steps away (meeting, AFK, slow to read) still finds a live entry when they tap the button, short enough that a genuinely abandoned prompt eventually unblocks the agent thread instead of pinning the running-agent guard forever. 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). Reads ``agent.clarify_timeout`` from config.yaml (see :func:`resolve_clarify_timeout` for the full resolution order). Set to ``0`` (or negative) for an unlimited wait — never auto-skip while the user is still deciding. r load_configr)hermes_cli.configrrr9rs rget_clarify_timeoutrsT 111111&{{}}':;;; tts ! //z*Dict[str, Callable[[_ClarifyEntry], None]] _notify_cbscbCallable[[_ClarifyEntry], None]NonecZt5|t|<ddddS#1swxYwYdS)zDRegister a per-session notify callback used by ``clarify_callback``.N)r,r)rrs rregister_notifyrsv &&#% K &&&&&&&&&&&&&&&&&&s $$ct5t|ddddn #1swxYwYt|dS)zLDrop the per-session notify callback and cancel any pending clarify entries.N)r,rr>rrs runregister_notifyrs ++ T***++++++++++++++++s 044)Optional[Callable[[_ClarifyEntry], None]]cxt5t|cdddS#1swxYwYdSrg)r,rr7rs r get_notifyrs{ ,,{++,,,,,,,,,,,,,,,,,,s /33)F) r r rr rr rrrrrr )r r r1r2rr)r r rr rr)rr rLrrrM)r/r rr rr)r/r rZr rr)rr rr rr)r r rr)rr rr)rr rrV)rrrrV)rrV)rr rrrr)rr rr)rr rr)'r$ __future__rloggingr&r: dataclassesrrtypingrrrr getLoggerr!loggerr RLockr,r)r%r*r0rFrJrPr^rUrzr|rrrrrrrrr(r rrsd>#""""" ((((((((111111111111  8 $ $          *  %''''''))))) 62222r    $$)29999x15151515h*    AAAA8.>;= <<<<&&&& ,,,,,,r