PR #11898: feat(feishu): intelligent reply on document comments with 3-tier access control

• Repository: NousResearch/hermes-agent
• Author: teknium1
• State: closed | merged: True
• Link: https://github.com/NousResearch/hermes-agent/pull/11898

Description (problem / solution / changelog)

Salvage of #11023 onto current main, preserving @liujinkun2025's authorship on the feature commit.

Summary

Adds an event handler for Feishu/Lark drive comment notifications so users can @-mention the bot on document comments (local or whole-doc) and get LLM replies inline, with a 3-tier allowlist/pairing access control system.

Changes

• New handler (gateway/platforms/feishu_comment.py, 1383 LOC): parses drive.notice.comment_add_v1 events, filters self-replies/non-bot-targeted, fetches doc + comment metadata in parallel, builds local-comment or whole-doc timeline (20/12 msg caps), runs agent with feishu_doc/feishu_drive toolsets, chunks replies at 4000 chars, per-doc session cache (1h TTL, 50 msg cap).
• Access control (gateway/platforms/feishu_comment_rules.py, 424 LOC): exact-doc > wildcard > top-level > default resolution with per-field fallback. Policies: allowlist (static) or pairing (static ∪ runtime-approved store). Mtime-cached hot-reload. CLI: python -m gateway.platforms.feishu_comment_rules {status|check|pairing}. Explicit-grant only — no implicit allow-all mode.
• 5 new tools, scoped to the comment agent only (NOT added to _HERMES_CORE_TOOLS or any platform toolset): feishu_doc_read, feishu_drive_list_comments, feishu_drive_list_comment_replies, feishu_drive_reply_comment, feishu_drive_add_comment.
• Adapter wiring (gateway/platforms/feishu.py): +25 lines to register the event handler on both WebSocket and Webhook transports.
• Tests: 643 LOC across tests/gateway/test_feishu_comment{,_rules}.py and tests/tools/test_feishu_tools.py.

Follow-up polish on top of the contributor commit

• feishu_comment_rules.py: replaced import-time ~/.hermes expanduser fallback with get_hermes_home() from hermes_constants (canonical, profile-safe).
• feishu_doc_tool.py / feishu_drive_tool.py: dropped the asyncio.get_event_loop().run_until_complete(asyncio.to_thread(...)) dance — tool handlers run synchronously in a worker thread with no running loop, so the RuntimeError branch was always the one that executed. Now calls client.request directly. Unused asyncio import removed.
• test_feishu.py: updated the mock EventDispatcher builder to include register_p2_customized_event for the new drive.notice.comment_add_v1 registration.
• scripts/release.py: AUTHOR_MAP entry [email protected] → liujinkun2025.

Validation

Live Feishu tenant E2E not performed (no tenant available); the contributor has already verified that path internally per the original PR description.

Credit

Feature implementation by @liujinkun2025 in #11023. Their commit is preserved as the first commit on this salvage branch (rebase merge to retain authorship).

Closes #11465 Supersedes #11023

Changed files

• gateway/platforms/feishu.py (modified, +25/-0)
• gateway/platforms/feishu_comment.py (added, +1383/-0)
• gateway/platforms/feishu_comment_rules.py (added, +429/-0)
• scripts/release.py (modified, +1/-0)
• tests/gateway/test_feishu.py (modified, +5/-0)
• tests/gateway/test_feishu_comment.py (added, +261/-0)
• tests/gateway/test_feishu_comment_rules.py (added, +320/-0)
• tests/tools/test_feishu_tools.py (added, +62/-0)
• tools/feishu_doc_tool.py (added, +131/-0)
• tools/feishu_drive_tool.py (added, +429/-0)
• toolsets.py (modified, +15/-0)

PR #11023: feat: Feishu document comment intelligent reply with 3-tier access control

• Repository: NousResearch/hermes-agent
• Author: liujinkun2025
• State: closed | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/11023

Description (problem / solution / changelog)

Summary

Add support for responding to Feishu document comments (drive.notice.comment_add_v1 events) with LLM-powered intelligent replies, including a configurable 3-tier access control system.

Comment Handler

• Full event orchestration: parse comment event → filter → fetch doc meta + comment details → build timeline → run agent → deliver reply
• Smart timeline selection: local comments (max 20 entries), whole-document comments (max 12 entries)
• Long text chunking (4000 chars) for reply delivery with automatic fallback
• Cross-card session sharing per document (in-memory cache, 50 msg cap, 1h TTL)
• Semantic text extraction (strip @mention noise)
• Document link resolution via /wiki/v2/spaces/get_node
• OK reaction indicator while agent is processing

Tools (5 new)

• feishu_doc_read — read document raw content
• feishu_drive_list_comments — list document comments
• feishu_drive_list_comment_replies — list comment thread replies
• feishu_drive_reply_comment — reply to a comment
• feishu_drive_add_comment — add a whole-document comment

3-Tier Access Control (feishu_comment_rules.py)

• Priority: exact document rule > wildcard "*" rule > top-level config > code defaults
• Per-field fallback: enabled, policy, allow_from each resolve independently through the tiers
• Policies: allowlist (static list only) / pairing (static list ∪ runtime-approved store)
• Explicit-grant only: every user who triggers a reply must be listed in allow_from or in the pairing-approved store — there is no implicit allow-all mode
• Config: ~/.hermes/feishu_comment_rules.json, mtime-cached hot-reload (no restart needed)
• CLI: status / check <doc> <user> / pairing add|remove|list

Event Filtering

• Self-reply filter using generalized self_open_id (supports both tenant and future user-identity modes)
• Receiver check: only process events where the bot is the @mentioned target
• Notice type filter: only add_comment and add_reply

Files Changed

Config Example

{
  "enabled": true,
  "policy": "pairing",
  "allow_from": ["ou_global_reviewer"],
  "documents": {
    "*": { "policy": "pairing", "allow_from": [] },
    "docx:dxxExxxxxMxxmxxxxxxxx": { "policy": "allowlist", "allow_from": ["ou_doc_owner", "ou_teammate"] }
  }
}

Test Plan

• Allowlist policy: empty allow_from denies all users silently
• Allowlist policy: user in allow_from gets normal reply
• Exact document rule overrides top-level (doc allowlist + narrower allow_from, top pairing)
• Exact document rule overrides wildcard (doc allowlist, wildcard pairing)
• Wildcard rule applies when no exact match
• Pairing policy: unapproved user silently denied
• Pairing policy: CLI pairing add grants access immediately (hot-reload)
• Pairing policy: user listed in allow_from granted without CLI approval (union semantics)
• Self-reply filter: bot's own comments are skipped
• Receiver filter: comments not @mentioning the bot are skipped

Changed files

• gateway/platforms/feishu.py (modified, +25/-0)
• gateway/platforms/feishu_comment.py (added, +1383/-0)
• gateway/platforms/feishu_comment_rules.py (added, +424/-0)
• tests/gateway/test_feishu_comment.py (added, +261/-0)
• tests/gateway/test_feishu_comment_rules.py (added, +320/-0)
• tests/tools/test_feishu_tools.py (added, +62/-0)
• tools/feishu_doc_tool.py (added, +136/-0)
• tools/feishu_drive_tool.py (added, +433/-0)
• toolsets.py (modified, +15/-0)