Repository navigation
Add Lark/Feishu gateway (per-sender routing, card buttons over the long connection) - #13
Open
CamiloCaceres wants to merge 5 commits into
Open
CamiloCaceres wants to merge 5 commits into
CamiloCaceres wants to merge 5 commits into
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
lark-gateway/: a gateway that connects one Lark / Feishu bot app to AI Maestro over AMP, built on theslack-gatewaypattern (inbound router, outbound inbox poller, thread store, content security,amp-bootstrap, management API, Dockerfile, pm2 config).What is different from the existing gateways:
routing.yamlmaps each Lark user (open_id) to a person key and that person's agent, likewhatsapp-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. Rawopen_ids never reach agents.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.Design notes
WSClient,@larksuiteoapi/node-sdk1.76.0),im.message.receive_v1andcard.action.trigger. Events are written to a durable on-disk queue before the callback returns, deduped byevent_id/message_id, then routed throughPOST /api/v1/route. Transient errors (network, 5xx, 429) retry with capped backoff; permanent 4xx errors park inundeliverable-inbound/with one notice to the sender.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.sanitizeFilenamerules. The AMP 10-file / 25 MB limits produce a clear reply.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 setscontext.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).envelope.fromis 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.jsonsidecar. 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./health;/api/config,/api/stats,/api/activitybehindADMIN_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
/api/v1/routehas 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= Larkmessage_id) would close it; happy to send that as a follow-up PR to ai-maestro.envelope.signatureon inbox files. It relies on filesystem isolation (inbox mode0700, its own OS user / volume). The sibling gateways share this limitation; a key-lookup endpoint would let every gateway verify.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.open_id) → threaded replycontext.lark.to)parent_textwrapped, labelled with the quoted message's authorBugs 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:resourcecovers 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-wideno-explicit-any).npm run typecheck:lark: passes; Lark SDK calls are typed (noanyclient).npm test: 215 passed, 0 failed (Lark 35).@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