.cje8`UdZddlmZddlZddlZddlZddlmZmZddl m Z m Z m Z m Z ejeZeGddZejZiZded <iZd ed <d4dZd5dZd6dZddd7dZd8d!Zd9d"Zd:d#Zd;d$Zdd*Z!iZ"d+ed,<d?d0Z#d@d1Z$dAd3Z%dS)BuGateway-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<eejZd ed <d Z d ed <dZ ded<ddZ d S) _ClarifyEntryz5One pending clarify request inside a gateway session.str clarify_id session_keyquestionOptional[List[str]]choices)default_factoryzthreading.EventeventN Optional[str]responseFbool awaiting_textreturnDict[str, object]cd|j|j|j|jrt |jnddS)N)r rrr)r rrrlist)selfs 7/home/ice/.hermes/hermes-agent/tools/clarify_gateway.py signaturez_ClarifyEntry.signature:s:/+ -1\CtDL)))t    )rr) __name__ __module__ __qualname____doc____annotations__r threadingEventrrrrrrr r /s??OOOMMM    "U9?CCCECCCC"H""""M      rr zDict[str, _ClarifyEntry]_entrieszDict[str, List[str]]_session_indexr r rrrrrc t||||rt|ndt| }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 rrrr)r rr_lockr(r) setdefaultappend)r rrrentrys rregisterr/Ns !(2W dw--'    E FF$!!+r2299*EEEFFFFFFFFFFFFFFF Ls9BBBtimeoutfloatrcpt5t|}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?)r0z!waiting for user clarify response)r+r(gettools.environments.baser3 Exceptionr1time monotonicminrwaitpopr)rremover) r r0r.r3 unlimiteddeadlineactivity_stateslice_s remainingidss rwait_for_responserEgsh )) 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*rrct5t|}| 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(r6r rrset)r rr.s rresolve_gateway_clarifyrIs  Z(( = '/&:S]]]EN KOO 4sAAAFinclude_choice_promptsrKOptional[_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)r6r(r)rrKrDcidr.s rget_pending_for_sessionrOs   --3  CLL%%E}% )<    sA A.A..A25A2r.ct|}|js|S 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 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). rN)r striprint ValueErrorlencasefoldr)r.rtextidxchoices r_coerce_text_responser[s x==   D = $ii!m  C$$$$#em$$$$$$$}S!!-'' ==??c&kk//11::<< < <v;;$$&& & & & =   4s? A Ac~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). TrJNF)rOr[rIr )rrr.coerceds r!resolve_text_response_for_sessionr^sT $K M M ME }u#E844Gu "   rct5t|}| 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(r6r)r r.s rmark_awaiting_textr` s  Z(( =# sAAA A ct5t|pg}td|DcdddS#1swxYwYdS)zEReturn True when this session has at least one pending clarify entry.c3NK|] }t|duV!dSN)r(r6.0rNs r zhas_pending..s3@@S8<<$$D0@@@@@@rN)r+r)r6any)rrDs r has_pendingrhs AA  --3@@C@@@@@AAAAAAAAAAAAAAAAAAs5A  AArTct5tt|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|dSrc)r(r=rds r z!clear_session..&s&:::s8<<T**:::rNrrGrQ)r+rr)r=rrrH)rrDentries cancelledr.s r clear_sessionrns ;;>%%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. clarifyr0Nagentclarify_timeout)r6rT TypeErrorrU)roraws rresolve_clarify_timeoutrx9s ::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_configru)hermes_cli.configr{rxr8rzs rget_clarify_timeoutr}PsT 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_notifyrrsv &&#% K &&&&&&&&&&&&&&&&&&s $$ct5t|ddddn #1swxYwYt|dS)zLDrop the per-session notify callback and cancel any pending clarify entries.N)r+r~r=rnrs runregister_notifyrxs ++ T***++++++++++++++++s 044)Optional[Callable[[_ClarifyEntry], None]]cxt5t|cdddS#1swxYwYdSrc)r+r~r6rs r get_notifyrs{ ,,{++,,,,,,,,,,,,,,,,,,s /33) r r rr rr rrrr )r r r0r1rr)r r rr rr)rr rKrrrL)r.r rr rr)rr rr rr)r r rr)rr rr)rr rrT)rorprrT)rrT)rr rrrr)rr rr)rr rr)&r# __future__rloggingr%r9 dataclassesrrtypingrrrr getLoggerr loggerr RLockr+r(r$r)r/rErIrOr[r^r`rhrnrxr}r~rrrr'rrrsE>#""""" ((((((((111111111111  8 $ $          &  %'''''')))))22222r    $$)2))))X*    AAAA8.>;= <<<<&&&& ,,,,,,r