feat(gateway): feishu thread participation tracking (involved mode)

[wangyuyan-agent]

Summary

Adds thread participation tracking to the Feishu adapter. Once the bot replies in a thread (topic), subsequent messages in that thread no longer require @mention — matching Discord's default allow_user_messages: "involved" behavior.

                    Incoming message (group chat)
                              │
                              ▼
                     Has thread_id (root_id)?
                      /                \
                    No                  Yes
                    │                    │
                    ▼                    ▼
            Require @mention     Bot participated in
                    │            this thread?
                    │             /          \
                    │           No           Yes
                    │            │             │
                    │            ▼             ▼
                    │     Require @mention   BYPASS ─── respond
                    │            │                     without @
                    ▼            ▼
              Bot @mentioned?  Bot @mentioned?
               /       \        /       \
             No        Yes    No        Yes
              │         │      │         │
              ▼         ▼      ▼         ▼
           (drop)   respond  (drop)   respond
                                      + record
                                      participation

Prior Art

Project	Approach	Key Difference
Discord (OAB)	In-memory cache + API history rebuild on miss	Discord threads are channels → one API call rebuilds state seamlessly after restart
OpenClaw	Bot creates threads (topic-spawn) → always owner	No participation tracking needed
Hermes Agent	No tracking — strict @mention always	Different philosophy

Feishu API Fact-Check

Feishu's GET /im/v1/messages returns all messages in a chat with no per-thread filter (root_id must be matched client-side). Rebuilding participation state after restart would require scanning entire chat histories — impractical for active groups. This is why we use pure in-memory cache (same as Discord's data structure, minus the API rebuild path).

Changes

File	Change
gateway/src/adapters/feishu.rs	Add session_ttl_secs config, participated_threads cache, participation check in mention gating, record_participation on reply
docs/feishu.md	Add FEISHU_SESSION_TTL_HOURS env var + Thread Participation docs

Testing

Scenario	Result
@bot in thread → then message without @	✅ bot responds
Message without @ in main channel	✅ bot silent
Restart → message without @ in same thread	✅ bot silent (cache cleared)
Re-@bot → then message without @	✅ bot responds again
@bot2 in thread where bot1 participated	⚠️ bot1 also responds (known, see below)
cargo test — 99 passed, 0 failed	✅

Known Limitations

1. Multi-bot threads: All participated bots respond to every message (matches Discord involved default). Follow-up: multibot-mentions mode.
2. No persistence: Restart clears cache. Users re-@ once to re-engage. Feishu API doesn't support efficient per-thread history queries.
3. No /leave: Bot stays involved until TTL expires.

Follow-up Plan

Priority	Item
Next	multibot-mentions mode — require @mention when multiple bots are in a thread
Later	/leave command
Later	Persistence to PV (JSON file)

New Environment Variable

Variable	Default	Description
FEISHU_SESSION_TTL_HOURS	24	Thread participation cache TTL. Set 0 to disable.

Discord Discussion URL

https://discord.com/channels/1491295327620169908/1500160821567684660

[shaun-agent]

OpenAB PR Screening

This is auto-generated by the OpenAB project-screening flow for context collection and reviewer handoff.
Click 👍 if you find this useful. Human review will be done within 24 hours. We appreciate your support and contribution 🙏

• Title: feat(gateway): feishu thread participation tracking (involved mode)
• Source: feat(gateway): feishu thread participation tracking (involved mode) #744
• Status: moved to PR-Screening
• Generated at: 2026-05-05T15:31:33.875Z
• Discord thread: https://discord.com/channels/1488041051187974246/1501244763251408909

Screening report

## Intent

PR #744 adds Feishu thread participation tracking so the bot can continue responding inside a Feishu topic/thread after it has already been explicitly mentioned there.

The operator-visible problem is that Feishu currently behaves more strictly than Discord: every follow-up message requires an @bot mention, even after the bot is already part of the thread. That makes threaded conversations noisy and less natural for users.

Feat

Feature.

The PR introduces an “involved mode” behavior for Feishu group chat threads:

• First message in a thread still requires @bot.
• Once the bot replies in that thread, subsequent messages in the same thread can trigger the bot without another mention.
• Participation state is stored in memory with a configurable TTL.
• Restart clears participation state, requiring users to mention the bot again.
• Documentation adds FEISHU_SESSION_TTL_HOURS.

Who It Serves

Primary beneficiaries: Feishu end users.

Secondary beneficiaries: deployers and agent runtime operators who want Feishu behavior to better match Discord’s default involved-thread experience without requiring persistent storage or expensive Feishu history scans.

Rewritten Prompt

Implement Feishu thread “involved mode” participation tracking.

In gateway/src/adapters/feishu.rs, track thread/topic IDs where this bot has replied. For group messages with a Feishu root_id, allow follow-up messages without @bot only when the bot has previously participated in that same thread and the participation entry has not expired. Messages outside threads, or in threads with no active participation entry, must still require an explicit mention.

Add a configurable TTL via FEISHU_SESSION_TTL_HOURS, defaulting to 24 hours. Setting it to 0 should disable mention bypass behavior. Participation may be in-memory only for this PR. Do not scan full Feishu chat history to rebuild state after restart.

Update Feishu docs with the new env var, behavior, restart limitation, and known multi-bot caveat. Add or update tests for mention gating, TTL-disabled behavior, restart/cache-miss behavior, and thread/non-thread distinction.

Merge Pitch

This is worth advancing because it closes a concrete usability gap between Discord and Feishu: once a bot is part of a thread, users should not need to repeatedly mention it.

Risk profile is moderate. The main behavioral risk is over-response, especially in multi-bot Feishu threads where multiple bots may consider themselves involved. The likely reviewer concern is whether in-memory participation is acceptable and whether the mention-bypass logic is scoped tightly enough to Feishu thread IDs, bot identity, TTL, and group chat semantics.

Best-Practice Comparison

OpenClaw principles that are relevant:

• Explicit delivery routing: relevant. The bot should only bypass mention checks when routing is clearly tied to a known Feishu thread where this bot participated.
• Run logs: partially relevant. If mention bypass causes unexpected responses, logs should make it clear whether the message matched an active participation entry.
• Durable job persistence: not directly required here. This is conversational participation state, not queued job state.
• Isolated executions: not central to this PR.
• Retry/backoff: not central unless Feishu reply delivery failures affect whether participation should be recorded.

Hermes Agent principles that are relevant:

• Atomic writes for persisted state: not relevant if this remains in-memory only.
• Fresh session per scheduled run: not relevant.
• Self-contained prompts for scheduled tasks: not relevant.
• File locking to prevent overlap: not relevant unless persistence is added later.
• Gateway daemon tick model: not directly relevant.

The most applicable best-practice principle is explicit, bounded routing: the bypass should be narrow, observable, and easy to disable.

Implementation Options

Conservative option: strict in-memory involved mode
Keep the PR scoped to in-memory thread participation with TTL. Require @bot on cache miss, after restart, outside threads, and when TTL is disabled. Add focused tests and clear docs.

Balanced option: in-memory involved mode plus stronger observability and config shape
Accept in-memory tracking, but add structured logs/metrics around participation recording, bypass decisions, TTL expiry, and disabled mode. Make the config naming align with existing gateway adapter config conventions.

Ambitious option: persisted participation state with multi-bot policy
Persist participation state to a local JSON/database-backed store with atomic writes and optional locking. Add a configurable multi-bot policy such as involved, mention_when_multiple_bots, or strict_mentions. This would reduce restart friction but increases operational and review complexity.

Comparison Table

Option	Speed to ship	Complexity	Reliability	Maintainability	User impact	Fit for OpenAB right now
Conservative in-memory involved mode	High	Low	Medium	High	Medium-high	Strong
In-memory plus observability/config cleanup	Medium	Medium	Medium-high	High	High	Strongest
Persisted state plus multi-bot policy	Low	High	High if done well	Medium	Highest	Better as follow-up

Recommendation

Advance the balanced option.

The core behavior is useful and mergeable, but the next review should focus on tightening operational clarity: ensure the bypass decision is logged or otherwise inspectable, config behavior is explicit, and tests cover TTL-disabled, cache-miss, threaded, and non-threaded cases.

Keep persistence and multi-bot policy out of this PR unless the current implementation already makes them unavoidable. Those are legitimate follow-ups, but splitting them preserves a clean first merge: Feishu gets Discord-like involved-thread behavior with bounded in-memory state and a clear escape hatch.

[chaodu-agent]

🟢 PR #744 — feat(gateway): feishu thread participation tracking (involved mode)

Verdict: Approve with minor nits

What problem does it solve?

Feishu group chats require @mention for every message. Once the bot has replied in a thread, users expect it to keep responding without re-mentioning — matching Discord's allow_user_messages: "involved" default behavior.

How does it solve it?

Adds an in-memory participated_threads: HashMap<String, Instant> cache to the Feishu adapter. When the bot sends a reply in a thread, it records the thread_id. On subsequent messages in that thread, the mention-gating check is bypassed. TTL-based expiry (FEISHU_SESSION_TTL_HOURS, default 24h) and a hard cap of 1000 entries with LRU-style eviction prevent unbounded growth.

What was considered?

• API rebuild (Discord approach): Rejected because Feishu's message API has no per-thread filter — would require scanning entire chat histories.
• Persistence: Deferred. In-memory is acceptable since re-@mention after restart is low friction.
• Multi-bot threads: Known limitation documented; follow-up multibot-mentions mode planned.

Is this the best approach?

Yes. It mirrors the proven Discord pattern with appropriate adaptation for Feishu's API constraints. The implementation is clean and well-tested.

---

Detailed notes

🟢 INFO — Well done

• Excellent PR description with flow diagram, prior art comparison, and Feishu API fact-check
• Tests cover: bypass with participation, no-bypass without thread, eviction behavior
• session_ttl_secs = 0 correctly disables the feature (elapsed is never < 0)
• Eviction strategy (drop oldest half at 1000) is simple and effective for this use case
• Both ingress paths (WebSocket + webhook) are covered

🟡 NIT — Non-blocking suggestions

1. Duplicated participation-check block — The 8-line is_thread_participated extraction appears identically in handle_ws_message and webhook. Consider extracting to a helper like fn check_thread_participated(envelope, cache, ttl) -> bool to reduce copy-paste drift.

2. unwrap_or_else(|e| e.into_inner()) on poisoned mutex — This is fine for a cache (data loss is acceptable), but a brief comment explaining the choice would help future readers understand it's intentional.

3. Eviction could be more targeted — Dropping half the cache when hitting 1000 is fine, but a TTL-based eviction (skip entries already expired) during the same pass would be slightly more efficient. Very minor — current approach is acceptable.

🔴 SUGGESTED CHANGES — None

No blocking issues found.

[wangyuyan-agent]

Thanks for the review! All three nits addressed in 15f16d8:

1. Duplicated participation-check block → Extracted check_thread_participated() helper, both WebSocket and webhook paths now call it.
2. Poisoned mutex comment → Added explicit comments explaining intentional recovery (unwrap_or_else(|e| e.into_inner())) — cache data loss is acceptable vs panicking the gateway.
3. Eviction improvement → Now drops TTL-expired entries first (map.retain), then falls back to oldest-half eviction only if still over capacity.

[chaodu-agent]

LGTM ✅ — Clean implementation of Discord-style "involved" mode for Feishu threads. Solid foundation for the multibot-mentions follow-up (#746).

📋 Review — Four Questions

1. What problem does this solve?

In Feishu group chats, the bot requires @mention for every message. Once a user starts a conversation in a thread, having to @mention every follow-up is friction. This PR makes the bot remember threads it has replied in and auto-respond without @mention — matching Discord's default allow_user_messages: "involved" behavior.

2. How does it solve it?

• participated_threads cache: HashMap<String, Instant> behind Arc<Mutex<>> on FeishuAdapter
• check_thread_participated() helper checks if thread_id exists in cache and hasn't expired
• record_participation() called on successful reply — inserts thread_id with current timestamp
• Eviction: when cache exceeds 1000 entries → drop expired first → then oldest half
• FEISHU_SESSION_TTL_HOURS (default 24h) controls TTL
• parse_message_event gains is_thread_participated: bool param — bypasses mention gating when true and message is in a thread
• Both WebSocket and webhook paths pass the participation check result

3. What alternatives were considered?

PR documents:

• Discord approach (API history rebuild on miss) — impractical for Feishu since GET /im/v1/messages has no per-thread filter
• OpenClaw (bot creates threads, always owner) — different model
• Hermes Agent (strict @mention always) — different philosophy

Pure in-memory cache chosen as pragmatic middle ground.

4. Is this the best approach?

Yes. The design is minimal and correct.

🟢 INFO — Well done:

• Bypass only applies to threads (messages with root_id), main channel always requires @mention — correct scoping
• Poisoned-mutex recovery pattern is appropriate for a cache
• Two-phase eviction (expired first, then oldest half) is better than naive oldest-half
• Tests cover the key scenarios: bypass works, no-thread doesn't bypass, eviction works
• Documentation is clear and concise

🟡 NIT — Non-blocking:

1. FEISHU_SESSION_TTL_HOURS=0 is documented as "disable" but the code would set session_ttl_secs = 0, making ts.elapsed().as_secs() < 0 always false — effectively disabling participation. This works correctly but the behavior is implicit. A comment noting "0 = disabled" would help future readers.
2. The bot_turns cache still has the // TODO: add TTL eviction comment. Since you've now established the eviction pattern with participated_threads, consider a follow-up to apply the same pattern there.

🔍 Baseline Check (Step 0)

• Main branch has no participated_threads, no session_ttl_secs, no check_thread_participated, no record_participation
• parse_message_event on main takes 3 params (no is_thread_participated)
• Mention gating on main is unconditional for group messages
• All 167 additions are net-new value
• Second commit addresses review nits (extracted helper, improved eviction) — good iterative refinement

[thepagent]

Let's fix the NITs #744 (comment) @wangyuyan-agent

[wangyuyan-agent]

Second-round nits addressed in cb6a56e:

1. session_ttl_secs=0 comment → Added doc comment clarifying "Set to 0 to disable participation tracking entirely"
2. bot_turns TODO → Updated comment to note the eviction pattern is established; TTL eviction for bot_turns is a follow-up

[chaodu-agent]

All NITs addressed ✅ — helper extracted, mutex comments added, TTL=0 documented, bot_turns comment updated. CI green. Ready to merge.

[obrutjack]

NIT #2 addressed in ed533bb:

session_ttl_secs=0 cache accumulation → Added early-return at the top of record_participation() when session_ttl_secs == 0. Skips mutex lock and cache insertion entirely when the feature is disabled.

[obrutjack]

LGTM ✅ — Clean implementation, all nits addressed, CI green. Approved.