Skip to content

feat(feishu): answer an unreadable attachment instead of dropping it silently - #16980

Merged
iamwhatever merged 1 commit into
mainfrom
replace/feishu-unreadable-attachment-8228
Oct 5, 2026
Merged

iamwhatever merged 1 commit into
mainfrom
replace/feishu-unreadable-attachment-8228

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Someone who sends a file to the Feishu bot gets a one-line answer saying the channel reads text only, instead of silence.

Send a photo to the Feishu bot and nothing happens. Not an error, not a hint, not a reaction — silence. feishu/client.py drops any non-text message at the parse step, so the sender cannot tell a refused attachment from a dead WebSocket, a wrong App ID, a missing scope, or an allow-list rejection. The rational next move is to send it again — or to ask "did you get that?", which does get answered, making the first look like a bug.

Why it matters

messaging/attachments.py already exists to prevent precisely this, and says so: silently dropping an attachment is the original defect that module exists to fix, and callers are expected to surface IngestResult.rejections to the user. But a transport declaring files_inbound=False never reaches ingest, so it has no IngestResult to carry a reason and that mechanism never runs for it. The guarantee exists; two channels sit outside it, and Feishu is one.

Not a goal

  • iMessage, which also declares files_inbound=False and still drops silently. Its receive checks text ahead of is_own_echo, whose own comment calls its position load-bearing in both directions ("consuming it there would restore the loop while looking fixed"). Reordering a gate whose comment warns it can silently restore a message loop belongs in its own change.
  • Real attachment ingestion for Feishu. This answers that the channel cannot read the file; it does not start reading files.

What changed (motivation → approach → change)

The reply reuses the existing mechanism's shape. attachments.channel_reads_no_attachments() builds the same single bracketed, em-dash-separated segment every ingest rejection already produces. It lives in that module because that module owns rejection wording, so a channel that later gains real ingestion changes which function builds the string, not how it reads.

Three gates decide where the reply happens, and each is a security property: after authorize (an unauthorised sender still learns nothing), after the group gate (a bot merely sitting in an unlisted group does not announce itself to the room), and after the dedup window (lark's WS redelivery cannot answer one photo twice).

The parse step changed to make that possible. _handle_receive_v1 dropped the message before extracting open_id, and the transport is the only layer that knows whether a sender is authorised. The type is now decided after the sender, and an unreadable message is carried on with text="" and unsupported_type set. Empty text plus no unsupported_type still stops in receive exactly as before. The existing log line is untouched.

files_inbound moves ASPIRATIONAL → ENFORCED in test_capability_ledger.py, with its read site cited inline, per the migration contract that module documents. A channel declaring True is untouched: its attachments go through ingest as before.

The echoed message_type is treated as untrusted. It is platform-supplied and goes back to the sender, so it is stripped to [a-zA-Z0-9_] and length-capped: brackets and dashes are what a rejection line is made of, and leaving them in would let a crafted type forge a second bracketed segment.

Two review findings from the original fork PR (#8228) are fixed here:

  • The reply now runs the per-message governance ceiling inbound_permitted("feishu") before sending. The reply returns before the dispatcher, so it never reaches the dispatcher's own inbound_permitted gate — without this, an administratively-disabled channel would still respond to an authorised owner's attachment.
  • A failed reply no longer vanishes without a trace. The original fork PR tried to drop the message id and re-raise so a lark WS redelivery would answer the attachment again — but client._deliver dispatches receive through asyncio.run_coroutine_threadsafe and never awaits it, so the WS frame is acked the moment the handler returns and no redelivery is ever held back; the re-raise only surfaced in a future nothing reads. So the failure is logged instead (logger.exception), the id stays recorded, and no redelivery is courted. A failed reply now leaves the one trace it actually can — a log line.

Backwards compatibility

Compatible: no field is rejected, renamed, or removed. A frame that resolves to empty text with no unsupported_type still stops in receive exactly as before, and a transport declaring files_inbound=True is unaffected. The dataclass gains one optional field (unsupported_type: str = "") with a default, so every existing LarkInbound construction keeps working.

Removes nothing: the change only adds a reply path for a message that was previously dropped; no reader of any existing capability is affected.

Tests

New tests. TestUnreadableInboundIsAnswered pins the reply and, one test per gate, the deny paths that must stay silent — unauthorised sender, empty allow-list, unlisted group, unknown chat type — plus answered-once on redelivery, never-drives-a-turn, an allow-listed group is answered, a files_inbound=True transport answering nothing, a governance-disabled channel staying silent, and a failed send being logged (the id stays recorded; no redelivery is courted). TestChannelReadsNoAttachments pins the string's shape rather than its prose, including that post (rich text, not a file) gets its own wording. Client tests replace the old "ignored" assertion with the carry-through contract, including that a message with no sender is still dropped.

Manual verification

N/A — unit coverage is sufficient: every gate (authorize, group, dedup, governance, capability, send-failure) is exercised by a dedicated test, and the reply shape is pinned structurally.

Related Issues

Fixes #7848

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested a review from a team as a code owner October 5, 2026 09:14
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Supersedes #8228 (fork PR by @JiaDe-Wu). Rebased onto current main and re-authored as an in-repo PR so the same-repo review lanes adjudicate the two security-class findings the fork pipeline fenced; both are fixed here (governance ceiling before the reply, and dropping the dedup id on a transient send failure). Original author @JiaDe-Wu keeps commit authorship (Co-authored-by trailer records the fixes).

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 5, 2026
@github-actions

github-actions Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 778c506181305d813331d5a4f76c21649b6e2768 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Still to check: send one real image from an allow-listed account and confirm the reply arrives as a threaded answer. The tests only exercise mocked lark frames.

[DESIGN-REVIEWED] 778c506

Description read

[DESCRIPTION-READ] 64fd973891e9d55fd22944ae8f81ce0b56c65ebb2e3f9ed4ee184407709eb43a

That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed 778c506181305d813331d5a4f76c21649b6e2768 — this comment is updated in place on each push.

Review details

No findings block this merge.

FINDING — src/kiro_crew/messaging/transport.py:165 — the diff moves "files_inbound" from ASPIRATIONAL to ENFORCED in the capability ledger, and FeishuTransport.receive now branches on self.capabilities.files_inbound. The ChannelCapabilities docstring still lists it under "ASPIRATIONAL … nothing reads them yet … do NOT write code that assumes they are enforced". The Feishu section of the owning spec, docs/system-specs/modules/messaging.md (~6188–6200), also wasn't updated in the same commit, so it still doesn't describe unreadable messages being answered or taking a dedup slot. → Fix: move files_inbound into the ENFORCED part of that docstring with what reads it, and add the unreadable-message reply to the messaging.md Feishu section, including its place after the dedup gate.

[OPUS-REVIEWED] 778c506

Verdict parsed from the review's SHA-scoped output markers for commit 778c506181305d813331d5a4f76c21649b6e2768.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 778c506181305d813331d5a4f76c21649b6e2768: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — 🟡 CONCERNS

Premise-level review of 778c506181305d813331d5a4f76c21649b6e2768 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The files_inbound gate in the new reply path can never be True for Feishu, so this PR ships a branch only a test can reach, plus a ledger move to go with it.

Not justified as shipped

  • Item 7 — one consumer, generalized: if not self.capabilities.files_inbound: reads FEISHU_CAPABILITIES, which sets it False (feishu/transport.py:56) and is never changed anywhere in src/ (searched for FEISHU_CAPABILITIES|capabilities =: 1 assignment, transport.py:106). The True case is only built in test_a_channel_that_reads_files_does_not_answer. The ledger move ("files_inbound moves ASPIRATIONAL → ENFORCED") exists only because of this one read.
    Subtraction: delete the files_inbound check in FeishuTransport.receive, and leave files_inbound in ASPIRATIONAL in test_capability_ledger.py.
    Clears when: the check and the ledger move are removed, or a Feishu code path that sets files_inbound=True lands.

What this change ships

Inventory (9 items) — 8 justified

Intent: someone who sends a file to the Feishu bot gets a reply saying the channel reads text only, instead of silence. FIX (#7848).

  1. An allow-listed sender's image, file or audio in a DM gets a one-line reply — justified
  2. The same reply in an allow-listed group; unlisted groups stay silent — justified
  3. Feishu rich-text (post) messages get their own wording — justified
  4. No reply when governance has disabled the Feishu channel — justified
  5. The echoed message_type is stripped to letters, digits and _ and capped in length — justified
  6. A failed reply is logged with its traceback — justified
  7. The reply depends on the files_inbound capability; ledger moves it to ENFORCED — one consumer, generalized: the True case is never built outside tests
  8. The Feishu "Known gaps" doc now describes the reply — justified
  9. New helper channel_reads_no_attachments builds the reply text — justified

[FIRST-PRINCIPLES-REVIEWED] 778c506

Description read

[DESCRIPTION-READ] d46f31358d9725cb4900d55c1499cdf682caa41b32187cdaeeb68f43ad6bccf6

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Oct 5, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 778c506181305d813331d5a4f76c21649b6e2768 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 778c506

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 778c506181305d813331d5a4f76c21649b6e2768: <one-sentence reason>

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 5, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Self-review (crew-pr-reviewer, read-only): CHANGES NEEDED

Read-only review. The gate order is right: governance, the allow-list, the group gate and dedup all run before the reply. One defect. client._deliver uses run_coroutine_threadsafe and never awaits it, so the frame is acknowledged before send_message runs. No redelivery comes, so transport.py:398-405's _seen.pop + re-raise doesn't help, and the re-raised exception is lost in an unread future: a failed reply leaves no trace at all. Please log it instead and remove the redelivery test and comment. That also answers the open First Principles CONCERNS. Small nit: rich-text post messages get told "the file was not opened".

@iamwhatever
iamwhatever marked this pull request as draft October 5, 2026 16:00
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Moved to draft by crew-pr-reviewer (self-review gate).

The self-review comment above lists changes this PR still needs. GitHub does not let an author request changes on their own PR, and PR Readiness does not read human review decisions, so a draft is the signal: it keeps readiness at checking, turns auto-merge off, and stops this PR from merging until the listed points are fixed.

To resume: address each point in the self-review comment, push, then run gh pr ready 16980 and re-enable auto-merge if wanted. The next review round will re-check the new head.

@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 5, 2026
@iamwhatever
iamwhatever force-pushed the replace/feishu-unreadable-attachment-8228 branch from 6d69474 to 83b92cb Compare October 5, 2026 16:04
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Thanks — addressed in 83b92cbe64e0ee32ce4f6249c9e75f9efd912295.

1. Dead redelivery path (client._deliver never awaits). You're right. _deliver dispatches receive via asyncio.run_coroutine_threadsafe(handler(inbound), loop) and never reads the future, so the WS frame is acked the moment the handler returns — the handler has already returned by the time send_message runs. Nothing holds back an ack for a redelivery to depend on, so transport.py's _seen.pop(msg_id) + re-raise could only chase a frame that never comes, and the re-raised exception vanished into an unread future: a failed reply left no trace at all. Fixed: the except now logger.exception(...)s the failure instead of re-raising, and does not touch _seen. A failed reply now leaves a log line — the one trace it actually can.

2. First Principles CONCERNS. This answers it. That concern was the same defect (Item 4, "inherited (unverified premise)"): the rollback assumed a redelivery that cannot occur. With the redelivery assumption dropped and the failure logged, the premise is gone, not papered over.

3. Removed the redelivery test and comment. test_a_transient_send_failure_lets_the_redelivery_answer is deleted, along with the _seen.pop/re-raise comment. Replaced with test_a_failed_send_is_logged_and_leaves_a_trace: a send that raises is caught, receive does not propagate, the id stays recorded, and the failure is logged with exc_info. It fails on the old re-raise code (RuntimeError escapes) and passes on the fix — verified both ways locally.

4. Nit — post wording. Fixed. post is Feishu's rich-text message, not a file, so channel_reads_no_attachments now special-cases it to [Rich text — this channel reads plain text only; the content was not read] instead of claiming a "file was not opened". Still one bracketed, em-dash-separated segment; pinned by test_post_is_rich_text_not_called_a_file.

Design Review's note stands: the unit tests use a fake client, so a live-tenant send is still worth a manual check before merge.

…silently

Send a photo to the Feishu bot and nothing happened. Not an error, not a hint
-- silence. The sender could not tell a refused attachment from a dead
WebSocket, a wrong App ID, a missing scope, or an allow-list rejection.

`messaging/attachments.py` exists to prevent exactly this: "Silently dropping
an attachment is the original defect this module exists to fix ... Callers are
expected to surface IngestResult.rejections to the user." But a transport
declaring `files_inbound=False` never reaches `ingest`, so it has no result to
carry a reason and the mechanism never runs for it. #7551 added the operator's
log line for this drop; the sender's half was still missing.

Feishu now replies with `attachments.channel_reads_no_attachments()`, in the
same bracketed shape every `ingest` rejection already uses, so a channel that
later gains real ingestion changes which function builds the string rather than
how it reads.

Three gates decide WHERE the reply happens, and each is a security property:

- after `authorize`, so an unauthorised sender still learns nothing -- telling
  a stranger the bot is alive is a disclosure this channel deliberately avoids;
- after the group gate, so a bot merely sitting in an unlisted group does not
  announce itself to the room;
- after the redelivery-dedup window, so lark's WS replaying a frame cannot
  answer the same photo twice.

The parse step had to change to make that possible. `_handle_receive_v1`
dropped a non-text message before extracting the sender, and the transport is
the only layer that knows whether that sender is authorised. The type is now
decided after `open_id` and the message is carried on with an empty `text` and
`unsupported_type` set, so it can never be mistaken for an instruction and
never drives a turn. The existing log line is unchanged.

`files_inbound` moves ASPIRATIONAL -> ENFORCED in the ledger with its read
site cited, per the migration contract that module documents.

Scope: Feishu only. iMessage also declares `files_inbound=False`, but its
`receive` checks text ahead of `is_own_echo`, whose position its own comment
calls load-bearing in both directions -- reordering it "would restore the loop
while looking fixed". That belongs in its own change.

The platform-supplied `message_type` is echoed back, so it is stripped to a
word and length-capped first: brackets and dashes are what a rejection line is
made of, and leaving them in would let a crafted type forge a second segment.

Co-authored-by: iamwhatever <12429733+iamwhatever@users.noreply.github.com>
@iamwhatever
iamwhatever force-pushed the replace/feishu-unreadable-attachment-8228 branch from 83b92cb to 778c506 Compare October 5, 2026 16:22
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Follow-up on 778c506181305d813331d5a4f76c21649b6e2768:

  • First Principles BLOCK (description/code mismatch): fixed by updating the PR description, not the code. The code's log-only decision is the intended one; the body now says so — the stale "drops the message id ... re-raises ... answered once" bullet and the "redelivery answer once" test phrase are gone, replaced with "logged, id kept, no redelivery courted". The post rich-text wording is noted in Tests.
  • Backend Lint & Type Check: a black formatting nit in the new test (any(...) folded to one line); reformatted and amended. Still one squashed commit. isort/flake8/mypy clean locally.

@iamwhatever
iamwhatever marked this pull request as ready for review October 5, 2026 17:05
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 5, 2026

@buluoray buluoray left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Verdict: APPROVE

Reviewed at 778c506.

No blocking findings. I did not run the full suite. I ran only the four directly related test files (189 passed) plus the mutation runs described below. CI on this head: 86 pass, 12 skipping, 0 failing.

What I verified

The reply goes to the right conversation only.

  • src/kiro_crew/feishu/transport.py:393-396: the reply is send_message(inbound.message_id, …). That resolves to im.v1.message.reply anchored on the inbound message id (transport.py:205-222, client.py send_reply), so it threads under the sender's own message in the chat it came from. This is the same anchor the text path uses. No chat_id or open_id is taken from anywhere else, and nothing is sent proactively. If message_id is empty the send raises (transport.py:219-220), the except catches it, and the failure is only logged. In practice client.py drops id-less frames before this point.
  • The reply sits after every existing gate, in order: the chat-type gate (transport.py:319), the group allow-list conjunction (:331), authorize (:351) and dedup (:364-372). It then also passes the per-message governance ceiling inbound_permitted("feishu") (:391). The default text="" keeps the cancel exemption off (messaging/dispatch.py:500-523), so a governed-off channel stays silent.
  • Fail-closed classification: every new guard is a return before any send. If a guard is wrong, the result is the old silent drop, not an extra or misdirected reply. The one fail-open direction, answering someone who is not authorised, is covered by the deny tests below.

No bytes, paths or credentials leak.

  • client.py:325-345 never reads message.content for a non-text message, so no file key, image key or download happens. The LarkInbound carries only open_id, message_id, chat_type, chat_id and the type string.
  • messaging/attachments.py:140-166: the reply text is a fixed template plus message_type, stripped to [a-zA-Z0-9_] and capped at 32 characters. No path, id or exception text gets into the reply. The logger.exception line in transport.py:405-410 goes to the operator log only.

No reply loop. The reply is always msg_type("text"). A redelivery or echo of it would therefore take the existing text path, never the unsupported_type branch. Dedup sits before the reply, so a redelivered image is answered once. Unknown senders, including other bots, fail authorize.

The readable path is unchanged. For message_type == "text" the only change is that the type decision now comes after the open_id extraction, and the extraction was already an early return. The run_coroutine_threadsafe hand-off moved into _deliver (client.py:398-409) byte for byte. In receive, if not inbound.text and not inbound.unsupported_type (transport.py:311) still stops empty text frames. A files_inbound=True transport falls through to return with no reply and no dispatch. That is the right result, because unsupported_type is only set for non-text frames.

Mutation results. I made six mutations in the worktree, restored each from a backup, and confirmed git status was clean afterwards.

Guard neutered Named test that reddened
inbound_permitted check → if False test_feishu_transport.py::…::test_a_governance_disabled_channel_stays_silent
files_inbound check → if True …::test_a_channel_that_reads_files_does_not_answer
sanitizer removed test_messaging_attachments.py::…::test_a_platform_kind_cannot_forge_a_second_segment
dedup membership check removed …TestUnreadableInboundIsAnswered::test_a_redelivered_frame_is_answered_once (+2)
receive text gate reverted to if not inbound.text …::test_an_image_from_an_authorised_sender_is_answered (+5)
except re-raises instead of logging …::test_a_failed_send_is_logged_and_leaves_a_trace

Non-blocking follow-ups

  1. Stale docstring. The ChannelCapabilities docstring in src/kiro_crew/messaging/transport.py (~line 165-170) still lists files_inbound under ASPIRATIONAL ("nothing reads them yet"). The ledger test now classes it as ENFORCED. Move it to the enforced list and name the read site at feishu/transport.py:384.
  2. Spec drift. The Feishu section of docs/system-specs/modules/messaging.md was not updated. It should say that an unreadable message is answered after the dedup gate (so it takes a dedup slot) and passes the governance ceiling. AGENTS.md asks for this in the same commit.
  3. Group behaviour depends on scope. With the at-mention-only group scope, images never reach the bot in groups. With the receive-all-group-messages scope, every image an allow-listed user posts in an allow-listed group will get the reply. That matches how text already behaves under that scope, but the doc line "in a group only one that is allow-listed too" could mention it.
  4. No live check yet. As Design Review notes, nobody has sent a real image from an allow-listed account. Do one live check before relying on the threaded reply.

Bot concern dispositions

  • Opus 5.5 (no blocking; FINDING on the docstring and spec): checked, still true at head. It covers documentation only, not behaviour, so it does not gate. Recorded as follow-ups 1-2.
  • First Principles (CONCERNS: the files_inbound branch is unreachable for Feishu): checked. FEISHU_CAPABILITIES sets it False and nothing in src/ changes it, so the True arm is reachable only in tests. It does not gate. The check is one line, it fails closed, and it ties the reply to the capability that a later ingestion change will flip. Without it, that change would leave the "not opened" reply firing next to real ingestion. Keeping it is a defensible design choice, not a defect.
  • Design Review (PASS, asks for a live send): this is a manual check. It does not gate. Recorded as follow-up 4.
  • GPT 6.1 (no findings): nothing to dispose of.
  • Earlier First Principles BLOCK (the description said re-raise, the code logs): the author fixed the description, and the code's log-only choice is correct. _deliver never awaits the future, so a re-raise would be invisible. Confirmed at client.py:408-409.

@iamwhatever
iamwhatever merged commit 5d6fa18 into main Oct 5, 2026
102 of 108 checks passed
@iamwhatever
iamwhatever deleted the replace/feishu-unreadable-attachment-8228 branch October 5, 2026 18:15
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 5, 2026
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.

A file sent to a channel that cannot read files gets silence, not an answer (files_inbound is declared but unread)

3 participants