PR #11740: fix(feishu): drop non-approval card callbacks instead of replying "Unknown command /card" (#11600)

• Repository: NousResearch/hermes-agent
• Author: briandevans
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/11740

Description (problem / solution / changelog)

What does this PR do?

Fixes #11600.

The Feishu adapter has a dead-end code path: every card.action.trigger callback whose payload does not carry a hermes_action key is converted into a synthetic /card <tag> <value> MessageType.COMMAND event and pushed through the gateway slash-command dispatcher. Because Hermes has never registered a card command, the dispatcher falls through to the Unrecognized slash command branch at gateway/run.py:3319 and replies to the user with:

Unknown command /card. Type /commands to see what's available, or resend without the leading slash to send as a regular message.

That reply fires on every click in any interactive card that isn't one of Hermes's own approval cards — and, critically, it also fires when a real approval callback's payload shape doesn't quite match _handle_approval_card_action's expectations (SDK version drift, proxy wrappers, etc.), which is the exact release-level symptom #11600 reports on v0.9.0. The user then gets a misleading "Unknown command" reply that has nothing to do with approvals, while the pending approval silently fails to resolve.

Root cause

gateway/platforms/feishu.py:2168 synthesises /card <tag>:

synthetic_text = f"/card {action_tag}"
...
synthetic_event = MessageEvent(
    text=synthetic_text,
    message_type=MessageType.COMMAND,
    ...
)
await self._handle_message_with_guards(synthetic_event)

Grep for card handler registration:

$ python -c "from hermes_cli.commands import GATEWAY_KNOWN_COMMANDS; print('card' in GATEWAY_KNOWN_COMMANDS)"
False

…and hermes_cli/commands.py / COMMAND_REGISTRY do not define one. The /card synthesis was documented at website/docs/user-guide/messaging/feishu.md:220-228 as a generic extension point but was never wired up to anything. The feature landed with the original Feishu integration in ca4907df (#3817) and has been unreachable since.

Smallest safe fix

• _handle_card_action_event becomes a log-and-drop handler. It still walks the SDK event shape to maintain the 15-minute dedup token cache (so repeat SDK deliveries don't re-log) and emits a compact DEBUG line with the action_tag and the keys of the value dict (never the raw value — user-typed payloads must not land at INFO). No synthetic command, no _handle_message_with_guards call.
• Approval branch is completely unchanged. Hermes-generated cards still carry hermes_action in their button value and route through _on_card_action_trigger → _handle_approval_card_action → _resolve_approval exactly as before. See the green/red resolved-card tests in TestCardActionCallbackResponse, all unchanged.
• Updated website/docs/user-guide/messaging/feishu.md to describe the actual behaviour (approval cards work, unrecognized card callbacks are dropped) instead of the aspirational /card claim.

Compat / behaviour truth table

No user-facing behaviour is silently lost — the only removed path was one that produced a misleading error reply.

Narrow scope — why only the log-drop

I deliberately did not:

• Introduce a new MessageType.CARD_ACTION event type. That's a feature, not a fix. If plugin extensibility for Feishu card events is desired later, it can be added as an additive follow-up without re-introducing the misleading /card reply.
• Try to repair why some approval-card clicks fail to resolve at all (the other half of #11600's first symptom). That depends on SDK event shape behaviour that this repo can't observe without a trace from the reporter — it belongs in its own investigation. Dropping the /card synthesis at least means that when an approval path fails, the user stops seeing a wrong-looking "Unknown command" reply, so the separable bug becomes observably separate in production.
• Extend the GATEWAY_KNOWN_COMMANDS allow-list to include card. Making the dispatcher not complain about an unimplemented command would hide a real design gap.

Pre-emptive reviewer Q&A

Q: Could anyone depend on the /card synthesis? No registered command handles it; no plugin hook consumes it. The behaviour was exclusively "user sees Unknown command /card". External dependency on that is implausible.

Q: Should the drop log at INFO? No. These callbacks fire on every user click on any non-Hermes card in a shared chat. INFO-level logging would be noisy for anything larger than a demo deployment. DEBUG is reachable via HERMES_LOG_LEVEL=DEBUG for anyone actually debugging Feishu card flows.

Q: Why log value keys but not the full value? Feishu cards can embed user-typed strings in the value payload. Keys are bounded metadata (card authors control them); full values can be arbitrary text including PII. Keys-only preserves debuggability without routing user content through INFO/DEBUG logs.

Q: What happens to the P2CardActionTriggerResponse return value now that non-approval callbacks don't schedule agent work? Unchanged. _on_card_action_trigger still returns P2CardActionTriggerResponse() for non-approval callbacks — Feishu's SDK requires some response to the callback so the button doesn't spin forever. We just don't push an agent event onto the loop.

Q: Dedup cache behaviour? Still maintained. The first callback for a given token logs its drop; subsequent deliveries of the same token short-circuit via the existing _is_card_action_duplicate check. Covered by test_duplicate_token_still_deduped.

Q: Security? The drop path is strictly less privileged than the synthesise-command path: we now don't forward user-controlled action_tag / action_value strings into the agent pipeline as a command. That removes a small but real injection surface: a card author could have crafted an action.value whose JSON serialization contains slash-command tokens, and every click would have sent that as a /card … command under a Hermes-user-looking MessageEvent. The new drop path never constructs a MessageEvent at all, so the agent pipeline never sees card-supplied strings.

Regression coverage

tests/gateway/test_feishu_approval_buttons.py — the pre-existing test_routes_as_synthetic_command (which pinned the broken behaviour) is replaced with test_non_approval_callback_does_not_synthesize_command (same code path, inverted assertion). Plus 4 new tests:

• test_non_approval_callback_does_not_synthesize_command — no MessageEvent emitted, no chat-info / sender-profile lookups wasted.
• test_duplicate_token_still_deduped — processed-token cache still recognises repeat SDK deliveries.
• test_non_dict_action_value_is_safe — SDK variant / malformed payload (action.value as a string) doesn't crash.
• test_missing_chat_id_is_safe — truncated payloads still handled.
• test_non_approval_trigger_does_not_reach_approval_handler — pins the routing invariant end-to-end through _on_card_action_trigger.

On unpatched origin/main, 3 of these tests fail with the expected "_handle_message_with_guards should not have been called. Called 1 times" / similar assertion errors, confirming they catch the regression. The remaining two pin behaviour preserved by the fix.

How to test

1. Focused suite:

   source venv/bin/activate
   python -m pytest tests/gateway/test_feishu_approval_buttons.py -q

   → 22 passed (17 existing + 5 new).

2. Verify the tests catch the bug on origin/main:

   git stash push gateway/platforms/feishu.py
   python -m pytest tests/gateway/test_feishu_approval_buttons.py::TestNonApprovalCardAction -v

   → 3 fail with _handle_message_with_guards was called 1 times. Restore with git stash pop.

3. CI-aligned broad suite:

   python -m pytest tests/ -q --ignore=tests/integration --ignore=tests/e2e --tb=short -n auto

   → 12385 passed, 39 skipped, 7 pre-existing baseline failures (tests/gateway/test_matrix.py, tests/gateway/test_approve_deny_commands.py ×2, tests/hermes_cli/test_gateway_wsl.py ×2, tests/tools/test_file_staleness.py ×2). All 7 reproduce on clean origin/main with identical assertions — none in the touched code path.

Tested on: macOS 15 (Darwin 25.5.0), Python 3.11.15.

Related Issue

Fixes #11600

Related / adjacent (not fixed here): #9585, #10073, #9533, #10256, #10412, #10301, #10801 — several of these may have been partially masked by the same /card noise. After this lands, the signal-to-noise on future Feishu approval reports should improve because the dispatcher can no longer conflate approval failures with unknown-command replies.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• gateway/platforms/feishu.py: rewrite _handle_card_action_event as log-and-drop; update _on_card_action_trigger docstring; update send_exec_approval docstring to reference the actual handler chain.
• tests/gateway/test_feishu_approval_buttons.py: replace test_routes_as_synthetic_command with test_non_approval_callback_does_not_synthesize_command, add 4 additional regression tests.
• website/docs/user-guide/messaging/feishu.md: rewrite the "Interactive Card Actions" section to describe actual behaviour.

Adjacent surfaces checked

• _handle_approval_card_action / _resolve_approval / send_exec_approval — unchanged; approval resolution path verified by the (untouched) TestResolveApproval and TestCardActionCallbackResponse suites.
• _is_card_action_duplicate / dedup token cache — unchanged; new test pins it still works.
• _on_card_action_trigger — only docstring + one added clarifying comment; routing logic byte-for-byte unchanged.
• GATEWAY_KNOWN_COMMANDS / hermes_cli/commands.py — confirmed card is not registered anywhere (see "Root cause" above).
• Other gateway platforms (matrix.py, slack.py, etc.) — none synthesize /card; no cross-platform impact.
• Plugin hooks — grepped hooks.emit / invoke_hook for any card:* event names; none exist.

Checklist

Code

• I've read the Contributing Guide
• Commit messages follow Conventional Commits (fix(scope):)
• Searched for existing PRs — none on #11600
• Only changes related to this fix
• Ran the CI-aligned test command and classified failures baseline-vs-change
• Added tests for my changes (5 new; 3 fail on origin/main without the fix, 2 pin preserved behaviour)
• Tested on macOS 15 (Darwin 25.5.0), Python 3.11.15

Documentation & Housekeeping

• Updated website/docs/user-guide/messaging/feishu.md to describe actual behaviour
• No config-key changes
• No architecture/workflow changes
• Cross-platform impact: none — only touches the Feishu adapter
• No tool descriptions/schemas touched

Notes for reviewers

• No standalone lint command is defined; CI runs python -m pytest tests/ -q --ignore=tests/integration --ignore=tests/e2e --tb=short -n auto (matches .github/workflows/tests.yml).
• No hermes_cli/** changes — the Nix workflow should not trigger.

Changed files

• gateway/platforms/feishu.py (modified, +52/-37)
• tests/gateway/test_feishu_approval_buttons.py (modified, +118/-10)
• website/docs/user-guide/messaging/feishu.md (modified, +4/-6)