Feishu WebSocket: inbound im.message.receive_v1 not handled (wrong asyncio loop)

[yanniszhou]

Summary

When Feishu channel connection_mode is websocket, the bot can send messages via the REST API, but user → bot messages often never reach process_feishu_event, so the agent appears to ignore DMs. Outbound traffic still works because it does not depend on the event pipeline.

Root cause

In backend/app/services/feishu_ws.py, the Lark SDK invokes the registered handle_message callback from a worker thread, where there is usually no running asyncio event loop.

The code uses asyncio.get_running_loop() and loop.create_task(self._async_handle_message(...)). That fails with RuntimeError in the common case. The fallback tries to guess the main loop via asyncio.all_tasks()[0].get_loop(), which is non-deterministic and unreliable, so the coroutine may never run on the FastAPI loop.

Expected behavior

Every im.message.receive_v1 event should be serialized and executed on the same event loop that runs FastAPI (e.g. via a loop captured at start_client / start_all and asyncio.run_coroutine_threadsafe from the SDK callback thread). The payload should be normalized to the same dict shape as the HTTP webhook before dispatch.

Suggested fix (high level)

1. Store a reference to the main loop when starting the WS client from async startup.
2. In the sync WS callback, parse the event into a body_dict (same shape as webhook).
3. Dispatch with asyncio.run_coroutine_threadsafe(_async_handle_message(agent_id, body_dict), main_loop) and log exceptions from the returned Future.

Optionally normalize connection_mode with .strip().lower() so values like WebSocket still enable WS mode.

Environment

• Feishu / Lark app: event subscription via long connection (WebSocket), not HTTP callback.
• Backend: FastAPI + lark-oapi WS client as in this repo.

---

Happy to open a PR with the above if maintainers agree with the direction.

[Clawiee]

Thank you for the detailed analysis @yanniszhou! 🙏

I've reviewed the code in backend/app/services/feishu_ws.py and confirmed your diagnosis. The root cause is exactly as you described:

Confirmed Issues

1. Asyncio loop issue in handle_message: The callback runs in a worker thread where asyncio.get_running_loop() raises RuntimeError, and the fallback asyncio.all_tasks()[0].get_loop() is indeed unreliable.

2. Data type mismatch: There's also a subtle bug where the normal code path (try block) passes data (the raw object) to _async_handle_message, while the error path (except RuntimeError) doesn't pass anything at all to run_coroutine_threadsafe. This inconsistency means the fallback path never actually dispatches events.

3. connection_mode normalization: Values like "WebSocket" (with capital W) won't match the comparison mode == "websocket".

Proposed Solution

Your suggested approach is sound:

1. Capture the main loop reference when starting the WS client
2. Use asyncio.run_coroutine_threadsafe from the sync callback
3. Normalize connection_mode with .strip().lower()

I'll tag this issue for the backend team (@nap-liu @商航) to prioritize. Since you offered to open a PR, we'd welcome the contribution! Please feel free to proceed with the fix.

@姚劲 @覃睿 @湛雨桐 - FYI for awareness.