Pmj+ dZddlZddlmZmZmZdZdefdZdZ deefdZ d#d ed eeed e d eedef dZ de fdZ dddddddddieddddddd gddZddlmZmZejdded e d!"dS)$a^ 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)ListOptionalCallablereturnc|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 8/home/thesage/.hermes/hermes-agent/tools/clarify_tool.py z"_flatten_choice..7s*66q**666666) isinstancestrstripdictgetlisttuplejoin)ckeyvs rrrs$ yr!Swwyy!T< ! !Cc A!S!! !aggii !wwyy   r!dE]##?xx66A66666<<>>> q66<<>>rcddld} |}|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|]}|jjjkVdSr)kind Parameter VAR_KEYWORD)rpinspects rrz#_invoke_callback..IsA8 8 89AFg'3 38 8 8 8 8 8 r)r$)r* signature parametersanyvalues TypeError ValueError)callbackquestionchoicesr$ accepts_multisigparamsr*s @r_invoke_callbackr7;sNNNM ))&&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|ESrr)rrs r z0_parse_multi_select_response.._s9GGG1A GA GGGr[cg|]D}t|#t|ESr:r;)rr)s rr=z0_parse_multi_select_response..hs9III1#a&&,,..IA IIIrc^g|]*}||+Sr:)rrss rr=z0_parse_multi_select_response..ms- ; ; ;! ;AGGII ; ; ;r,) rrrr startswithjsonloadsJSONDecodeErrorsplit) raw_responserawparseds r_parse_multi_select_responserLVs,%%HGG GGGG l   ! ! # #C ~~c Z__F&$'' JIIIIII J#    D  < ;syy~~ ; ; ;;s4BB! B!Fr2r3r$r1c||r|stdS|}|et|tstdSdd|DD}t |t kr|dt }|sd}|tdS t ||||}n)#t$r}td|cYd}~Sd}~wwxYw|r|t|}n!t|}tj |||dd S) a 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. callback: Platform-provided function that handles the actual UI interaction. Signature: ``callback(question, choices, multi_select=False) -> str``. The optional ``multi_select`` keyword is passed so the platform can render checkboxes instead of radio buttons. Injected by the agent runner (cli.py / gateway). Returns: JSON string with the user's response. zQuestion text is required.Nz"choices must be a list of strings.cg|]}||Sr:r:rAs rr=z clarify_tool..sIIIqI1IIIrc34K|]}t|VdSrr)rr s rrzclarify_tool..s*CCaq11CCCCCCrz8Clarify tool is not available in this execution context.zFailed to get user input: )r2choices_offered user_responseF) ensure_ascii) r tool_errorrrlen MAX_CHOICESr7 ExceptionrLrrEdumps)r2r3r$r1rIexcrQs r clarify_toolrYps6 88>>++86777~~H'4(( DBCC C JICC7CCCIII w<<+ % %l{l+G GTUUU>'(G\RR >>>2+4\BB L))//11 :"&    s3C C,C'!C,'C,cdS)z>Clarify tool has no external requirements -- always available.Tr:r:rrcheck_clarify_requirementsr[s 4rclarifyu]Ask 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. 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. 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 arrayr_aREQUIRED whenever you are presenting selectable options: each distinct option is its own array element (up to 4). 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.)r_itemsmaxItemsr 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).)r2r3r$)r_ propertiesrequired)namer r,)registryrSc t|dd|d|dd|dS)Nr2r r3r$Fr1)r2r3r$r1)rYr)argskws rrksU|*b))##XXne44 ##  % % %ru❓)rftoolsetschemahandlercheck_fnemoji)NFN)__doc__rEtypingrrrrUrrr7rLboolrYr[CLARIFY_SCHEMAtools.registryrgrSregisterr:rrrws   ++++++++++  #B'''6<$s)<<<<8$(#' @@@ d3i @@x @  @@@@FD  C0!G  (+'S  "S+  > LC""5==B0///////    % % (       r