feat(channels): add first-party Feishu / Lark channel

[himax12]

Summary

• Add a messenger-only first-party feishu channel (display name Feishu / Lark) over the Open Platform persistent connection (WebSocket). No webhook, cards, Drive, or custom Desktop screens.
• Pairing and allowlists use Feishu open_id (ou_*). Groups default to mention-only (matches the default @bot event scope). @all is not a bot mention. Bot/app senders are dropped.
• One running listener per App ID (cluster mode). domain selects Feishu (open.feishu.cn) vs Lark (open.larksuite.com). Text send goes through the shared MessageChannel tool.
• appId / appSecret / domain land on the existing flattened ChannelPluginAccountPatch (same shared create/update path as Signal), not a new discriminated patch union.

Closes #4130.

Why

Mainland Feishu and international Lark are the same Open Platform with different consoles. A first-party plugin is what makes letta channels configure/install/pair work without a user-plugin manifest. Persistent connection is the local analog of Slack Socket Mode.

Limits / non-goals

• No published ./channels/feishu package export (Slack/Telegram subpaths shipped because Cloud needed them). Pure ingress.ts / outbound.ts stay SDK-free for a later webhook host.
• No HTTP webhook, Card Kit, docs/drive/Bitable, store apps, or allowBots.
• Self-built apps only. Restart the listener after editing accounts.json.

Verification

• bun run check — 12/12
• bun test src/channels/feishu src/channels/registry-community-copy.test.ts — 34 passed
• Lifecycle errors go through formatChannelLifecycleErrorMessage (adapter test covers sanitizing before post).
• Mention-only drop, message_id dedup, and second App ID start are covered by tests that fail without this change.

Live validation

No live Feishu/Lark app probe was run. Harness-only: injected SDK client, ingress/outbound unit tests, and the App ID uniqueness guard.

AI Disclosure

• This pull request was written entirely by a human
• This pull request was written with AI assistance and reviewed and edited by a human
• I have read the AI Policy and agree to its terms

AI Tool(s) Used

Cursor

Human Verification

I have reviewed and understand every change in this pull request and take responsibility for its correctness.

Made with Cursor

Linear: https://linear.app/letta/issue/LET-11920/add-first-party-feishulark-channel-support

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[lipracer]

match on a field the payload does not have. refer https://open.feishu.cn/document/server-docs/im-v1/message/events/receive

[lipracer]

Nice structure overall — follows the existing channel conventions and skipping
media downloads avoids a lot of trouble. One blocker though.

P0: group @mentions are never detected, so group chat does nothing by default.

isFeishuBotMention() has two ways to detect a mention and both are broken:

// A — field does not exist in the payload
if (mentions.some((m) => m.mentioned_type === "bot")) return true;
// B — never runs: botOpenId is always null
const trimmedBotOpenId = botOpenId?.trim();
if (!trimmedBotOpenId) return false;
return mentions.some((m) => m.id?.open_id === trimmedBotOpenId);

[himax12]

Agreed — thanks for catching this. mentioned_type isn't on the live im.message.receive_v1 mention object, and we were also passing botOpenId: null, so both checks were dead and mention-only groups dropped everything.

Fixed in d6fcaa4: start calls GET /open-apis/bot/v3/info, then isFeishuBotMention() matches mentions[].id.open_id against that bot open_id. mentioned_type is ignored. Tests cover the official-shaped payload (no mentioned_type), a mentioned_type: bot red herring.

[lipracer]

Re-reviewed after the update — the P0 is resolved, and the fix is more thorough
than what I suggested. Removing mentioned_type from the FeishuMention
interface (not just from the check), extracting parseFeishuBotInfo so
account-display.ts reuses it, and clearing botOpenId on all three teardown
paths all look right.

The regression test is the part I'd single out: keeping a fixture that still
carries mentioned_type: "bot" while pointing open_id at a different user,
and asserting the message is dropped, locks the bug out permanently rather than
just fixing it.

One new point — and a correction to my earlier suggestion

I argued for failing start() when /open-apis/bot/v3/info fails. You chose to
warn and continue, and you're right that hard-failing would break DM-only setups
over a call that path doesn't need.

The current shape has no recovery path, though. A single transient failure at
startup leaves botOpenId null for the whole session, and because isRunning()
reports true the channel looks healthy while every group @mention is silently
dropped. The only clue is one startup warning that has long scrolled away.

A lazy retry covers both cases better than either fail-fast or warn-once: on the
first mention-only group event, if botOpenId is still null, resolve it again
with simple backoff — only on the group path, so DMs stay unaffected. Transient
failures then self-heal, and persistent ones keep producing log lines instead of
a single one that was easy to miss.

Still open from the earlier pass

Both non-blocking as far as I'm concerned:

• senderName is resolved by searching mentions for the sender, but that array
  holds mentioned users, so in practice it falls back to the raw ou_... id.
• start() sets running = true before the socket settles and installs no
  close/error handler, so isRunning() stays true after a mid-session
  disconnect. Worth confirming whether WSClient reconnects internally.

Standing

I'm not a code owner on this repo and can't approve or gate the merge — please
treat this as a drive-by review from someone who wants this channel to land, not
as a required sign-off.

_{Reviewed with Comate CLI (model: Opus 5). Findings were verified
against the PR diff and the Feishu im.message.receive_v1
documentation; no live tenant test was run on my side either.}