Skip to content

Add Lark/Feishu gateway (per-sender routing, card buttons over the long connection) - #13

Open
CamiloCaceres wants to merge 5 commits into
23blocks-OS:mainfrom
CamiloCaceres:feat/lark-gateway
Open

CamiloCaceres wants to merge 5 commits into
23blocks-OS:mainfrom
CamiloCaceres:feat/lark-gateway

Conversation

@CamiloCaceres

@CamiloCaceres CamiloCaceres commented Oct 31, 2026 •

Copy link
Copy Markdown

Summary

Adds lark-gateway/: a gateway that connects one Lark / Feishu bot app to AI Maestro over AMP, built on the slack-gateway pattern (inbound router, outbound inbox poller, thread store, content security, amp-bootstrap, management API, Dockerfile, pm2 config).

What is different from the existing gateways:

  • Per-sender routing. routing.yaml maps each Lark user (open_id) to a person key and that person's agent, like whatsapp-gateway's phone routing. DMs go to the sender's own agent; unknown senders and paused people get a configurable reply; group messages are ignored except for a one-line pointer when the bot is mentioned. Raw open_ids never reach agents.
  • Trust per target agent. A message from the agent's owner is passed unwrapped; everything else (other senders, forwarded messages, quoted parent text) is wrapped as external content and scanned.
  • Card buttons. Agents can attach up to five buttons to a reply (context.lark.buttons); clicks come back to the owning agent as AMP requests (context.lark.card_action), the clicker sees a short toast, and only the card's owner can click them. Clicks arrive over the long connection by default, so the gateway needs no public ingress; an HTTP callback mode is available as an opt-in.
  • Progress signal. A reaction is added to the user's message when it is routed and swapped when the reply posts; one "still working" line after a configurable delay.

Design notes

  • Inbound: Lark long connection (WSClient, @larksuiteoapi/node-sdk 1.76.0), im.message.receive_v1 and card.action.trigger. Events are written to a durable on-disk queue before the callback returns, deduped by event_id / message_id, then routed through POST /api/v1/route. Transient errors (network, 5xx, 429) retry with capped backoff; permanent 4xx errors park in undeliverable-inbound/ with one notice to the sender.
  • Message types: text, post (with inline images), image, file, audio, merge_forward (expanded, wrapped as forwarded data), sticker (ignored). Bot mentions are stripped; human mentions are replaced with display names.
  • Attachments use AI Maestro's attachment API (init, content, confirm, status) and are sent as AMP references; outbound attachments are fetched by reference, and inline base64 is still accepted. File names are sanitized to Maestro's sanitizeFilename rules. The AMP 10-file / 25 MB limits produce a clear reply.
  • Outbound reads the real inbox layout (inbox/<sanitized-from>/<id>.json, with the 60-second empty-folder rule from Fix reply race: keep empty sender inbox folders for 60 seconds #12). Each multi-part reply (text chunks, cards, attachments) is checkpointed per part, so a retry never re-posts parts already sent. Markdown with structure becomes a Card JSON 2.0 card (its markdown element renders headings, tables and code blocks, which the 1.0 element shows as raw text), with no header unless the agent sets context.lark.title; plain text stays text; long messages are split under Lark limits at paragraph or line breaks. DMs get a normal quoted reply; topic threads are a config option (LARK_REPLY_IN_THREAD).
  • Outbound authorization: a reply is delivered only when envelope.from is the agent recorded on that thread; an agent-initiated DM (context.lark.to) only from that person's configured agent. Anything else is parked with a .reason.json sidecar. The one "could not be delivered" notice goes only to the conversation the sender was authorized for (re-checked on every attempt), so a misbehaving agent cannot use the notice to reach a person it does not serve.
  • Ops: /health; /api/config, /api/stats, /api/activity behind ADMIN_TOKEN; bind address and tenant discovery follow fix: configurable bind address so Docker port mapping works (loopback by default) #9 and Gateways: discover AMP tenant from AI Maestro; Google Chat bold prefix #11; SDK logs are filtered so request bodies (ids, message text) never reach logs; Docker runs as a configurable UID/GID so it can own the inbox, and mounts the routing directory so hot reload works. Without credentials the container starts in health-only mode and logs one clear configuration error.

Delivery guarantees and known limitations

  • At-least-once routing window. /api/v1/route has no idempotency key today. If Maestro accepts a message and the gateway stops before saving the response id, that message is routed again after restart. The restart soak below measures this window: 101 route requests for 100 messages. An idempotency key on /api/v1/route (e.g. idempotency_key = Lark message_id) would close it; happy to send that as a follow-up PR to ai-maestro.
  • Inbox signatures are not verified. AI Maestro does not expose a sender's public key, so the gateway cannot verify envelope.signature on inbox files. It relies on filesystem isolation (inbox mode 0700, its own OS user / volume). The sibling gateways share this limitation; a key-lookup endpoint would let every gateway verify.
  • Live-tested, with gaps. See "Live test" below. Not yet exercised live: a card click by a non-owner (needs a second Lark user), unknown and paused senders, and restarts with messages in flight. These are covered by the fake-event tests.

Lark Developer Console setup

Step by step in lark-gateway/README.md: create the app, enable the bot, the exact permission scopes, event subscription via persistent connection, Callback Configuration → persistent connection → card.action.trigger, and publishing a version.

Live test

Run against a real Lark app installed in a Lark test company, AI Maestro v0.106.40 on Linux under pm2, the gateway from this branch under pm2, and Claude Code agents in Maestro's tmux runtime (one answering by hand via amp-send, one answering on its own). Synthetic data only.

Check Result
DM → agent (C1 payload, slug only, no open_id) → threaded reply ✅
Agent-initiated DM (context.lark.to) ✅
"Still working on it." after 30 s; done reaction on reply ✅
Markdown card: headings, table, quote, code block, nested list, link ✅ (after moving to Card JSON 2.0)
Card button click over the long connection → agent request; toast shown ✅
Quoted reply → parent_text wrapped, labelled with the quoted message's author ✅ (quoting a Card 2.0 card gives a placeholder: Lark's message API does not return Card 2.0 text)
Combined forward → expanded and wrapped as forwarded data ✅
Image and PDF in (1.5 MB) / CSV and PNG out ✅
102 KB reply → split into ordered cards at line breaks ✅
Group: no mention → silence; mention → one pointer line; nothing routed ✅
Reply from an agent that doesn't own the thread / DM → parked, nothing sent ✅

Bugs the live run found, fixed in this PR: Card 1.0 rendered headings and tables as raw text; an unauthorized agent's parked reply still sent the person a failure notice; long replies split mid-line; filenames with spaces or brackets fell back to the Lark file key; quoted text was labelled with the replier instead of its author; inbound line breaks were collapsed; the gateway's own forward marker tripped its injection scanner; cards carried a fixed "AI Maestro" header. An independent adversarial review of those fixes then found, and this PR fixes: a failure notice that could still be steered to another person; line-anchored injection patterns missed after the first line and loosely spelled wrapper tags not escaped; forwarded bodies able to fake a sender line; non-Latin filenames collapsing to _.pdf; @AIM: tags inside forwarded content selecting an agent. The README now lists the exact console steps that tripped us up (im:resource covers uploads; the persistent-connection setting only saves while a client is connected; open_ids are per app; test companies skip version review).

Test evidence

  • npm run lint: 0 errors (warnings are the existing repo-wide no-explicit-any).
  • npm run typecheck:lark: passes; Lark SDK calls are typed (no any client).
  • Root npm test: 215 passed, 0 failed (Lark 35).
  • Lark coverage: every message type; routing (owner, unknown, paused, group with and without mention, admin-only @AIM: tags); trust wrapping (forwarded, quoted parent); dedupe across restart; outbound text vs card, splitting, per-part checkpointing, permanent-error parking; sender authorization; attachments in and out with limits; agent-initiated DM; card click → agent → reply path, non-owner refusal, retry after a failed route; HTTP callback URL verification; and an in-flight restart soak: 100 DMs from 5 senders, the gateway torn down while routes are pending, then rebuilt. Result: 0 lost, 100 replies each delivered exactly once to the right DM, 0 parked, 1 re-routed message (the window above).
  • docker build ./lark-gateway: passes.

🤖 Generated with Claude Code

CamiloCaceres and others added 5 commits October 31, 2026 16:08
Ran the gateway against a real Lark app (a Lark test company) and AI
Maestro v0.106.40, then fixed what the live run and an adversarial
review found:

- Reply cards use Card JSON 2.0, so headings, tables and code blocks
  render; no header unless the agent sets context.lark.title.
- A parked reply notifies only the conversation its sender was
  authorized for, re-checked on every attempt; unauthorized senders
  park silently with a .reason.json sidecar.
- Long replies split at paragraph or line breaks.
- Inbound text keeps line breaks and indentation; forwarded bodies are
  indented so they cannot fake another sender line; @aim: tags inside
  forwards no longer select an agent.
- Quoted parents are labelled with their real author and wrapped as
  forwarded only when they are forwards; quoted cards fall back to a
  clear placeholder because Lark does not return Card 2.0 text.
- The injection scanner checks line-anchored patterns, skips only the
  gateway's own forward marker, and every spelling of the wrapper tags
  is escaped.
- Filenames keep their name with unsafe characters replaced; names in
  other scripts use the file key plus extension.
- README: live test status, console steps that tripped us up, Card 2.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant