sj_*dZddlZddlmZmZmZmZdZdZdZ dZ de fd Z d ee dee fd Z d e de fd ZdZdee fdZdefdZdefdZdedefdZdeededede fdZdeede de fdZ d8de d eee dedeeedeede f dZdefdZd d!d"d#d$d%d&d'd#ied(d)d*d+d%d&ed,d"d#d-d%d'd#id&d'd#ied.d'd*id/dgd0d1d2dgd0d3Zdd4lmZmZej d d ed5ed67dS)9a^ Clarify Tool Module - Interactive Clarifying Questions Allows the agent to present structured multiple-choice questions or open-ended prompts to the user. In CLI mode, choices are navigable with arrow keys. On messaging platforms, choices are rendered as a numbered list. Supports both single-select (radio) and multi-select (checkbox) modes via the ``multi_select`` parameter. The actual user-interaction logic lives in the platform layer (cli.py for CLI, gateway/run.py for messaging). This module defines the schema, validation, and a thin dispatcher that delegates to a platform-provided callback. N)DictListOptionalCallablezrThe user did not provide a response within the time limit. Use your best judgement to make the choice and proceed.z (Recommended)returnc|dSt|tr|St|tr[dD]V}||}t|tr*|r|cSWdSt|t t fr1dd|DSt|S)uCoerce a single choice into its user-facing display string. The schema declares choices as bare strings, but LLMs sometimes emit dict-shaped choices like ``[{"description": "..."}]``. A naive ``str(c)`` turns the whole dict into its Python repr — ``{'description': '...'}`` — which then leaks onto every surface that renders the choice (CLI panel, Discord buttons, Telegram numbered list) AND is returned verbatim as the user's answer. Normalising here, at the one platform-agnostic entry point, fixes the whole class in one place instead of per-adapter. Dict unwrap order is the canonical LLM tool-call user-facing keys: ``label`` → ``description`` → ``text`` → ``title``. ``name`` and ``value`` are deliberately excluded — they're component-shaped fields that could carry raw enum values or short identifiers, not human-readable labels. A dict with none of the canonical keys is dropped (returns ""), since a garbage label is worse than no choice at all. N)label descriptiontexttitle c34K|]}t|VdSN_flatten_choice).0xs 6/home/agent/.hermes/hermes-agent/tools/clarify_tool.py z"_flatten_choice..Hs*66q**666666) isinstancestrstripdictgetlisttuplejoin)ckeyvs rrr+s$ yr!Swwyy!T< ! !Cc A!S!! !aggii !wwyy   r!dE]##?xx66A66666<<>>> q66<<>>rchoicesct|dkr|St|d}|t|kr|S|dtgt |ddzS)uLabel the first choice as the agent's recommendation. The schema tells the model to order ``choices`` best-first, so element 0 is always the option it would pick itself. Tagging it here — the one platform-agnostic entry point — means every surface (CLI panel, TUI, desktop card, Telegram buttons) reads the same way without four copies of the same string concatenation, and the label can never drift between them. Idempotent: a model that writes its own "(recommended)" into the choice is left alone rather than getting the suffix twice. A lone choice isn't a recommendation — there's nothing to prefer it over — so single-choice lists pass through untouched. rrN)lenrrstrip_recommendedRECOMMENDED_LABELr)r%firsts rmark_recommendedr-Ls{ 7||a  OO ! ! # #E !%(((( * *( * * +d7122;.?.? ??rrc"t|}|tr/|dt t S|S)uBRemove the recommendation label from a resolved answer. The user picks the decorated string, but the agent asked about the bare option — returning "Rebase onto main (Recommended)" as ``user_response`` would leak presentation into the answer the model reasons about and into anything it echoes back. N)rrcasefoldendswithr+r))rstrippeds rr*r*bsv4yy  H##$5$>$>$@$@AA;1301111288::: Orcddld} |}|j}d|vp,tfd|D}n#t t f$rd}YnwxYw|r||||S|||S)ubInvoke the platform callback, passing multi_select if supported. Uses signature inspection (not a ``TypeError`` retry) to decide whether the callback accepts the ``multi_select`` keyword — a retry-on-TypeError approach would re-invoke a *compatible* callback that raised TypeError internally, potentially prompting the user twice. rNF multi_selectc3BK|]}|jjjkVdSrkind Parameter VAR_KEYWORDrpinspects rrz#_invoke_callback..~sA8 8 89AFg'3 38 8 8 8 8 8 r)r3r; signature parametersanyvalues TypeError ValueError)callbackquestionr%r3 accepts_multisigparamsr;s @r_invoke_callbackrHpsNNNM ))&&0 C8 8 8 8 =C]]__8 8 8 5 5  z "  Fx' EEEE 8Hg & &&sA AA-,A-ct|tr d|DSt|}|drL t j|}t|tr d|DSn#t j$rYnwxYwd|dDS)uParse a multi-select response into a list of cleaned choice strings. Handles three forms: - Already a list → stringify + strip each element - JSON array → parse and strip - Comma-separated → split, strip, drop empties cg|]D}t|#t|ESrrrrs r z0_parse_multi_select_response..s9GGG1A GA GGGr[cg|]D}t|#t|ESrKrL)rr:s rrOz0_parse_multi_select_response..s9III1#a&&,,..IA IIIrc^g|]*}||+SrK)rrss rrOz0_parse_multi_select_response..s- ; ; ;! ;AGGII ; ; ;r,) rrrr startswithjsonloadsJSONDecodeErrorsplit) raw_responserawparseds r_parse_multi_select_responser^s,%%HGG GGGG l   ! ! # #C ~~c Z__F&$'' JIIIIII J#    D  < ;syy~~ ; ; ;;s4BB! B!c t|tsdS|sdSt|tkr ddtdfSg}t |D]\}}t|t rd|i}t|t s dd|dfcSt |dpd }|s dd|d fcS|d }|`t|ts dd|d fcSd d|DD}t|tkr|dt}|sd}t |dpd pd}| d||||rtt|nd|rt|ndt|dot|d|dfS)uValidate and normalize the ``questions`` batch parameter. Returns ``(normalized, error)`` where exactly one is non-None, except the empty-list case which returns ``(None, None)`` — an empty array is not an error, it just means "no batch here" and the caller falls back to the single-question path. Each normalized entry carries: - ``qid``: stable wire id (``q0``..``qN``, index order). Surfaces key their per-question answers by this; a model-supplied ``id`` is NOT used on the wire (it's unvalidated text) and only echoed in results. - ``id``: the model's optional identifier, or None. - ``question``: stripped question text. - ``choices``: decorated choice list (recommended label applied), or None for open-ended. - ``choices_offered``: the bare list as offered, for the result JSON. - ``multi_select``: honored only when choices exist. )Nz/questions must be an array of question objects.)NNNzquestions supports at most z items.rDz questions[z&] must be an object with a 'question'.r z"].question must be non-empty text.r%z].choices must be a list.cg|]}||SrKrKrSs rrOz(_normalize_questions..sMMMQ1MqMMMrc34K|]}t|VdSrrrr"s rrz'_normalize_questions..s*"G"G!?1#5#5"G"G"G"G"G"Gridqr3)qidrcrDr%choices_offeredr3) rrr) MAX_QUESTIONS enumeraterrrr MAX_CHOICESappendr-bool) questions normalizedindexitemrr%model_ids r_normalize_questionsrqsc& i & &GFF z 9~~ %%I=IIIIIJ ++  t dC  &%D$%% TSeSSSS S S S488J''-2..4466 POeOOOO O O O((9%%  gt,, KJ%JJJJJJJMM"G"Gw"G"G"GMMMG7||k))!,;,/ txx~~+,,2244<u;;:AK'W 666t07AtG}}}T .!9!9::LtG}}        t rcddl |j}d|vp,tfd|DS#t t f$rYdSwxYw)uTrue when the platform callback understands the ``questions`` kwarg. Same signature-inspection approach as ``_invoke_callback`` (never a TypeError retry — that would re-prompt the user on an internal bug). rNrlc3BK|]}|jjjkVdSrr5r9s rrz._callback_accepts_questions..sA, , 89AFg'3 3, , , , , , rFr<)rCrGr;s @r_callback_accepts_questionsrts NNN""8,,7f$ , , , , =C]]__, , , ) )   z "uusA AA'&A'entrycb|drdt|DSt|S)zEStrip presentation from one locked answer (label, multi-select JSON).r3c,g|]}t|SrKr*rMs rrOz'_clean_batch_answer..s!PPP!!$$PPPr)r^r*)rur\s r_clean_batch_answerrys; ^QPP.J3.O.OPPPP S ! !!rrmanswers timed_outc6g}|D]t}i}|dr |d|d<|d|d<|d|d<||d}|rt||nd|d<||ud|i}|rd|d <tj|d S) uAssemble the batch result JSON from per-qid answers. Unanswered questions surface as empty ``user_response`` — with the top-level ``timed_out`` flag (present only when true) telling the agent whether those blanks are deliberate skips or the user walking away. rcrDrfrer user_response responsesTr{F ensure_ascii)rryrjrWdumps)rmrzr{r~rurowr\results r _batch_resultrsI ; $d CI +J!&'8!9 kk%,''BEM25#>>>2O!,i 8F#"{ :f5 1 1 11rrDct|rh||d|}i}d}|2t|tr!|tkrd}n t|t rGt |dpi}t|d}nt|tr|r tj |}n#tj $rd}YnwxYwt|t rFt |dpi}t|d}t|||Si}d}|D]i}t||d|d|d }|2t|tr!|tkrd}n |||d <jt|||S) uDispatch a validated batch to the platform callback. Batch-capable callbacks (a ``questions`` kwarg, detected by signature) get the whole list once and reply with ``{"answers": {qid: raw}}`` plus an optional ``timed_out`` flag — as a dict or a JSON string (the tui_gateway ``_block`` bridge can only carry strings). Legacy callbacks are looped one question at a time (messaging adapters, older plugins). An explicit empty answer is a skip and the loop continues; a timeout (``None`` or the ``TIMEOUT_RESPONSE`` sentinel) means the user walked away, so the loop aborts instead of pestering them with the remaining questions. Answers collected before the abort are kept either way. N)rlFTrzr{rDr%r3re) rtrrrTIMEOUT_RESPONSErrrkrWrXrYrrH)rmrCrDr\rzr{r]rus r _run_batchrs#8,,=hx<<< ;:c3//;CIIKKCS4S4SII T " " :3779--344GSWW[1122II S ! ! :ciikk : C'    &$'' :vzz)44:;; K!8!899 Z)<<<GI$$ eJ'y)95;P   ;:c3//;CIIKKCS4S4SI E #e  Wi 8 88s!C66D  D Fr3rlrCc|t|\}}|rt|S|rm|tdS t||t|pdS#t $r}td|cYd}~Sd}~wwxYw|r|stdS|}|et |tstdSdd|DD}t|tkr|dt}|sd}|tdS|}|t|} t||||} n)#t $r}td|cYd}~Sd}~wwxYw|r|d t| D} nt| } tj||| d d S) an Ask the user a question, optionally with multiple-choice options. Args: question: The question text to present. choices: Up to 4 predefined answer choices. When omitted the question is purely open-ended. multi_select: When True, the user can select multiple choices (checkboxes). The ``user_response`` in the output JSON will be a list of strings instead of a single string. Has no effect when ``choices`` is omitted. questions: Up to 5 independent questions asked as one batch (issue #18450). Each item: ``{id?, question, choices?, multi_select?}``. When present (non-empty), the single ``question``/``choices``/``multi_select`` parameters are ignored and the result JSON is ``{"responses": [...]}`` (plus ``"timed_out": true`` when the user stopped answering partway). callback: Platform-provided function that handles the actual UI interaction. Signature: ``callback(question, choices, multi_select=False) -> str``. Batch-capable platforms additionally accept a ``questions`` keyword and receive the normalized list in one call; platforms without it are looped one question at a time. Injected by the agent runner (cli.py / gateway). Returns: JSON string with the user's response(s). Nz8Clarify tool is not available in this execution context.r zFailed to get user input: zQuestion text is required.z"choices must be a list of strings.cg|]}||SrKrKrSs rrOz clarify_tool..sIIIqI1IIIrc34K|]}t|VdSrrrbs rrzclarify_tool..s*CCaq11CCCCCCrc,g|]}t|SrKrxrMs rrOz clarify_tool..s!bbb!*1--bbbr)rDrfr}Fr)rq tool_errorrrr Exceptionrrr)rir-rHr^r*rWr) rDr%r3rlrCrmerrorexcofferedr[r}s r clarify_toolrIs~J0;; E  %e$$ $  F!N F!*hHN8K8K8Q8Q8S8STTT F F F!"Ds"D"DEEEEEEEE F 88>>++86777~~H'4(( DBCC C JICC7CCCIII w<<+ % %l{l+G GTUUU G"7++>'(G\RR >>>8+bb7ST`7a7abbb ),77 :"&    s;1A,, B6B B BE-- F7FFFcdS)z>Clarify tool has no external requirements -- always available.TrKrKrrcheck_clarify_requirementsrs 4rclarifyuAsk the user a question when you need clarification, feedback, or a decision before proceeding. Supports three modes: 1. **Single-select multiple choice** — provide up to 4 choices. The user picks one or types their own answer via a 5th 'Other' option. List the choice you recommend FIRST: the UI labels it '(Recommended)' and highlights it by default. 2. **Multi-select multiple choice** — set multi_select=true. The user can select multiple options via checkboxes. user_response will be a list of selected choices. 3. **Open-ended** — omit choices entirely. The user types a free-form response. You can also ask SEVERAL questions in ONE call: pass questions in the `questions` array (each with its own choices/multi_select, any mix of the three modes). The user answers them all on a single form, in any order. STRONGLY preferred over a chain of single-question clarify calls when you need several independent answers. CRITICAL: when you are offering options, put each option ONLY in the `choices` array — NEVER enumerate the options inside the `question` text. The UI renders `choices` as selectable rows; options written into the question string render as dead prose the user can't pick. Right: question='Which deployment target?', choices=['staging', 'prod']. Wrong: question='Which target? 1) staging 2) prod', choices=[]. Use this tool when: - The task is ambiguous and you need the user to choose an approach - You want post-task feedback ('How did that work out?') - You want to offer to save a skill or update memory - A decision has meaningful trade-offs the user should weigh in on Do NOT use this tool for simple yes/no confirmation of dangerous commands (the terminal tool handles that). Prefer making a reasonable default choice yourself when the decision is low-stakes.objectstringuThe question itself, and ONLY the question (e.g. 'Which deployment target?'). Do NOT embed the answer options here — pass them as separate elements in `choices`.)typer arrayruREQUIRED whenever you are presenting selectable options: each distinct option is its own array element (up to 4). ORDER MATTERS: put the option you actually recommend FIRST — the UI labels it '(Recommended)' and pre-selects it, so a list ordered arbitrarily recommends the wrong thing to the user. Do not write '(Recommended)' yourself. The UI renders these as pickable rows and auto-appends an 'Other (type your answer)' option. Omit this parameter entirely ONLY for a genuinely open-ended free-text question.)ritemsmaxItemsr booleanzWhen true, the user can select MULTIPLE options (like checkboxes). The user_response will be a list of selected choices. When false (default), single selection (radio). Has no effect when choices is omitted (open-ended question).uAsk 2-5 INDEPENDENT questions in one call instead of several sequential clarify calls — the user answers them on one form, in any order. Each item has its own question/choices/multi_select (same rules as the top-level parameters); optional `id` is echoed back in the matching response. When set, the top-level question/choices are ignored. put a short batch title in the top-level `question` The result is {responses: [...]}, with `timed_out: true` added if the user stopped part-way (unanswered entries have an empty user_response). Only batch questions that are truly independent — if one answer would change another question, ask separately.zLOptional short identifier echoed in the matching response (e.g. 'approach').)rrr)rcrDr%r3)r propertiesrequired)rrr r)rDr%r3rl)namer r>)registryrc t|dd|d|dd|d|dS) NrDr r%r3FrlrC)rDr%r3rlrC)rr)argskws rr,sd|*b))##XXne44((;'' ##  % % %ru❓)rtoolsetschemahandlercheck_fnemoji)NFNN)!__doc__rWtypingrrrrrirgrr+rrr-r*rHr^r rqrkrtrrryrrrrCLARIFY_SCHEMAtools.registryrrregisterrKrrrs   111111111111   >$#B@d3i@DI@@@@, C C    '''6<$s)<<<<<;u;;;;|T""t"V""""2d4j242D2S22220/94:/93/93/9/9/9/9h$(&*#' ``` d3i ``T # ` x `  ````FD  C<!G  (+'S ""S ) L%%-!G&,X$6$+&,h%7(3$$ *0(;## ", %#%%EH H R LWLLAmmb0///////    % % (       r