feat(attachments): full attachment support — any file type, multiple per message (CHOO-1802)

[amaudruz]

Closes the gap described in CHOO-1802: attachments were effectively images-only, one at a time.

What was actually broken

Mapping the pipeline first paid off — most of the plumbing was already type-agnostic. The blocks were at the edges:

• Inbound: three literal if not mimetype.startswith("image/"): continue guards (Slack, Mattermost, Discord) that dropped non-image files to a debug log — a silent drop, and a direct violation of the repo's fail-loud rule.
• Outbound: a single if msgtype != "m.image" branch in bridge_core that posted _sent a file that isn't relayed yet_ instead of uploading. The else branch below it already handled any mimetype.
• Multiple attachments: the whole chain was one-file-per-call, and N inbound files became N separate messages.
• A real hole: the 20MB cap was enforced on the agent-upload and bridge-relay paths but not inbound at all.

Changes

Any file type, both directions

• Removed the three inbound image guards; removed the outbound m.image special case.
• Widened the channel tool's extension→mimetype map so type fidelity survives the round trip.

Multiple attachments per message

Matrix has no multi-attachment event — one media event carries one mxc, and MSC4274 / MSC2881 are unmerged. So a message with n files is sent as n events sharing a group marker (com.switch.attachment_group = {id, index, total}) and coalesced at both edges:

• bridge_core stamps the group inbound (a platform post hands us all its files at once, so the count is known up front — no guessing) and buffers outbound groups into one platform post via a new adapter send_attachments (Slack file_uploads, Mattermost file_ids — both native).
• agent_client buffers parts and emits a single payload carrying all attachments.
• send_attachment accepts paths; the media endpoint accepts repeated files parts.

An event with no marker is a group of one, so this is backward compatible with media already in rooms.

Fail loud, never fake

• Inbound size cap enforced (checked pre-download against the platform-reported size where available, and again post-download).
• Oversize / failed files are carried as AttachmentFailure and disclosed in the room, never dropped.
• A multi-file send validates every file before sending any — a bad file fails the whole call rather than half-posting a message.
• An incomplete group flushes after a timeout with an explicit "n of m" notice rather than hanging or vanishing.
• Non-image files reach the agent as file_path; unretrievable ones as failed_attachments.

Platform coverage — stated plainly

• Slack — implemented and verified (the reported case), including a genuine single multi-file post.
• Mattermost — implemented, including native multi-file posts. Not manually tested against a live server.
• Discord — inbound parity only (guard removed, failures disclosed).
• Teams — unchanged; it has no inbound byte path at all.

Testing

644 passed, 0 failed; ruff + mypy clean. (141 errors in a local run are the pre-existing Postgres-dependent store tests — no DB in that environment.)

New coverage: parse_attachment_group edge cases, inbound group stamping + failure disclosure, outbound batching, and agent-side coalescing (in-order, out-of-order, ungrouped, and incomplete-with-timeout, asserting no buffer/timer leak).

Writing the tests surfaced three real defects in the first pass, fixed in 6548217 — each with a regression test verified to fail against the prior code:

1. bool is a subclass of int, so {"index": false} parsed as index 0 instead of being rejected.
2. The flush timer was re-armed per part, so the timeout bounded the gap between parts, not the group — a slow dribble could hold the buffer open indefinitely. Now armed once per group.
3. Coalesced payloads were anchored on whichever part arrived last, making message_id unstable. Both paths now anchor on part 0.

Notes

• No migration needed; alembic heads prints exactly one head (b3f36489c258).
• SKILL.md updated for the changed agent-facing contract; plugin version bumped 0.2.0 → 0.3.0 per repo policy.

🤖 Generated with Claude Code

[github-actions]

Thank you for your contribution! Before we can merge it, please read our Contributor License Agreement and sign it by posting the following comment on this pull request:

---

I have read the CLA Document and I hereby sign the CLA

---

switch-worker-louis-remote seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}