feat(gateway): bridge clarify tool to messaging platforms#23740
Closed
bladeJumper wants to merge 1 commit into
Closed
feat(gateway): bridge clarify tool to messaging platforms#23740bladeJumper wants to merge 1 commit into
bladeJumper wants to merge 1 commit into
Conversation
Adds gateway-side infrastructure for the clarify tool, enabling interactive questions with choice buttons on messaging platforms (Feishu, extensible to Telegram/Discord). Root cause: AIAgent() was constructed without clarify_callback in gateway/run.py, so clarify_tool.py got callback=None and returned an error JSON to the model. Architecture mirrors the existing approval system: - tools/clarify_state.py: core bridge with per-session blocking queue - gateway/run.py: injects clarify_callback into AIAgent, adds clarify_notify_sync dispatcher (card-based with text fallback) - gateway/platforms/feishu.py: send_clarify_prompt() sends interactive cards with choice buttons; _handle_clarify_card_action() resolves the blocked agent thread on button click Key design decisions: - Clarify cards use hermes_action=clarify_* namespace, routed separately from approval actions - Multiple concurrent clarify prompts supported via clarify_id - Other button defers resolution: card updates to prompt user to type their answer, then text-intercept logic in run.py resolves with the actual typed text (Feishu cards cannot present text input fields) - Open-ended questions (no choices) show text hint, not buttons - clarify_callback import moved to usage site to avoid potential circular dependency Tests: 14 new tests in test_clarify_state.py, all passing.
13 tasks
bladeJumper
added a commit
to bladeJumper/hermes-agent
that referenced
this pull request
May 21, 2026
Implements the clarify tool on Feishu with interactive card buttons, mirroring the Telegram pattern from NousResearch#24199. - send_clarify: renders question + choice buttons as Feishu interactive card - _handle_clarify_card_action: routes button callbacks via hermes_clarify_action - choice: resolves immediately with choice text - other: flips to text-capture mode via mark_awaiting_text - Already-resolved guard prevents double-click / stale-button issues - Authorization check reuses _is_interactive_operator_authorized - Choice text lookup: stored state → clarify entry → fallback index Known limitation: Feishu shows both the tool-progress bubble (❓ clarify: ...) and the interactive card because Feishu lacks delete_message support. This can be revisited once Feishu implements message deletion. Closes NousResearch#12573 Closes NousResearch#21032 Supersedes NousResearch#23740 (which included framework code now merged in NousResearch#24199) Related NousResearch#24199, NousResearch#21893, NousResearch#503
Author
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The
clarifytool returns"Clarify tool is not available in this execution context."when running via the gateway —gateway/run.pynever passesclarify_callbacktoAIAgent(), so the tool is completely non-functional on all messaging platforms.Closes #12573
Closes #21032
Supersedes #12576
Related #18301, #21893, #503
Comparison with #12576
#12576 (by @tymrtn) wires the callback but only supports plain-text replies — the user must type their answer as a normal message, with no inline buttons or visual feedback. This PR extends that approach with:
clarify_state.py) — platform-agnostic, designed for reuse by Telegram/Discord adaptersChanges
tools/clarify_state.py— new file, state managementClarifyStatedataclass: question, choices, session_key, resolve callbackset_gateway_clarify/resolve_gateway_clarify/cancel_gateway_clarify— gateway-side lifecycleget_gateway_clarify— for gateway to check pending statetools/clarify_tool.py— gateway-aware resolve_gateway_live), yields control back to the gateway instead of blocking on stdingateway/run.py— bridge the clarify lifecycle_clarify_liveis setclarify_callbackimport to usage site (avoids circular dependency)gateway/platforms/feishu.py— Feishu interactive cardsend_clarify(): question + choice buttons as interactive card_handle_clarify_card_action(): button click resolutiontests/tools/test_clarify_state.py— new file, 300 linesTesting
Adding Other Platforms
The
clarify_state.pymodule is platform-agnostic. To add Telegram support:send_clarify()to the Telegram adapter (inline keyboard)callback_queryto callresolve_gateway_clarify()run.pyalready handles free-form inputSame pattern applies to Discord (reaction-based, per #21893).
Files Changed
tools/clarify_state.py— new filetools/clarify_tool.py— gateway-aware resolve pathgateway/run.py— clarify lifecycle bridge + text interceptorgateway/platforms/feishu.py— interactive card rendering + handlertests/tools/test_clarify_state.py— new test file