`gj-pUdZddlmZddlZddlZddlZddlmZmZddl m Z m Z m Z m Z ejeZeGddZej$ZiZded <iZd ed < dd Zdd ZddZdd d dZd!dZd"dZd#dZd$dZd%dZd&dZ iZ!ded<d'dZ"d(dZ#d)dZ$y)*uGateway-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 y ) _ClarifyEntryz5One pending clarify request inside a gateway session.str clarify_id session_keyquestionOptional[List[str]]choices)default_factoryzthreading.EventeventN Optional[str]responseFbool awaiting_textc|j|j|j|jrt |jdSddS)N)r rrr)r rrrlist)selfs H/root/.hermes/venv/lib/python3.12/site-packages/tools/clarify_gateway.py signaturez_ClarifyEntry.signature:sF//++ -1\\tDLL)   @D   )returnzDict[str, object]) __name__ __module__ __qualname____doc____annotations__r threadingEventrrrrrrr r /sG?OM  "9??CE?C"Hm"M4 rr zDict[str, _ClarifyEntry]_entrieszDict[str, List[str]]_session_indexc t||||r t|ndt| }t5|t|<t j |gj|ddd|S#1swY|SxYw)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.Nsw !(W dw-'  E F$!!+r299*EF LF Ls /A''A1ct5tj|}dddy ddlm}t jt|dz}t jt jd} |t jz }|dkrn3|jjtd|rn | ||dPt5tj|dtj|j}|r7||vr3|j||s tj|jdddd|j S#1swY8xYw#t $rd}Y?wxYw#1swY|j SxYw) uBlock 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. Returns the resolved response string, or ``None`` on timeout. Nr)touch_activity_if_dueg) last_touchstartg?)timeoutz!waiting for user clarify response)r*r'gettools.environments.baser0 Exceptiontime monotonicmaxrwaitminpopr(rremover)r r3r-r0deadlineactivity_state remainingidss rwait_for_responserBgsU ) Z() }%A~~#gs"33H$(NN$4t~~?OPN t~~// >  ;;  CY$7  8  , !.2U V  < Z&  !2!23 :$ JJz """5#4#4d;< >>=)) % $%< >>s)EE A/E2E E/.E/2Fct5tj|}| dddy ddd| t|nd_|j j y#1swY8xYw)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'r4r rrset)r rr-s rresolve_gateway_clarifyrFsd  Z( = '/&:S]EN KKOO  s A!!A*Finclude_choice_promptsct5tj|xsg}|D]5}tj|}||s |js*|ccdddS dddy#1swYyxYw)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(r4r'r)rrHrAcidr-s rget_pending_for_sessionrKsu   -3 CLL%E}%)<)<   sAA% A%A%%A.ct|j}|jr t|dz }d|cxkrt |jkrnn|j|S|jD]U}|j t|jj k(s">"@@6{((** + K C sC CCcbt|d}|yt|jt||S)zFResolve the oldest pending clarify in ``session_key`` from typed text.TrGF)rKrFr rW)rrr-s r!resolve_text_response_for_sessionrYs6 #K ME } " eX. rct5tj|}| dddyd|_ dddy#1swYyxYw)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'r4r)r r-s rmark_awaiting_textr[sI  Z( =# s ::Act5tj|xsg}td|DcdddS#1swYyxYw)zEReturn True when this session has at least one pending clarify entry.c3JK|]}tj|duywN)r'r4).0rJs r zhas_pending..s@S8<<$D0@s!#N)r*r(r4any)rrAs r has_pendingrbsA A  -3@C@@AAAs +<Ac6t5ttj|gxsg}|Dcgc]}tj|d}}dddd}D]+}|d|_|j j|dz }-|Scc}w#1swYBxYw)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. NrrDrM)r*rr(r<r'rrrE)rrArJentries cancelledr-s r clear_sessionrfs ;>%%k26<"=69:s8<<T*::;I  =   Q   ;;;s(BB  B BBc ddlm}|xsi}|jdixsi}t|jddS#t$rYywxYw)u;Read 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. r) load_configagentclarify_timeouti)hermes_cli.configrhr4rPr6)rhcfg agent_cfgs rget_clarify_timeoutrn sT1m!rGGGR(.B 9==!2D9:: sAA AAz*Dict[str, Callable[[_ClarifyEntry], None]] _notify_cbscLt5|t|<dddy#1swYyxYw)zDRegister a per-session notify callback used by ``clarify_callback``.N)r*ro)rcbs rregister_notifyrr*s$ &#% K &&&s #c|t5tj|ddddt|y#1swYxYw)zLDrop the per-session notify callback and cancel any pending clarify entries.N)r*ror<rfrs runregister_notifyru0s2 + T*++ ++s2;cdt5tj|cdddS#1swYyxYwr^)r*ror4rts r get_notifyrw9s& ,{+,,,s&/) r r rr rr rrrr )r r r3floatrr)r r rr rr)rr rHrrzOptional[_ClarifyEntry])r-r rr rr )rr rr rr)r r rr)rr rr)rr rrP)rrP)rr rqzCallable[[_ClarifyEntry], None]rNone)rr rry)rr rz)Optional[Callable[[_ClarifyEntry], None]])%r" __future__rloggingr$r7 dataclassesrrtypingrrrr getLoggerrloggerr RLockr*r'r#r(r.rBrFrKrWrYr[rbrfrnrorrrurwr&rrrs># (11   8 $     &  %' "'')$)!   2(^ $$)! 2   A8<;= 7<& ,r