[5620] fix(api): classify plain ZIP attachments correctly

[Bharani010]

Summary

Uploading a plain ZIP through /sessions/attachments stored it with the DOCX media type. ZIP and DOCX share the same container signature, and PureMagic selected the more specific Word type without checking whether the archive contained Word structures.

Before:

notes.zip -> application/vnd.openxmlformats-officedocument.wordprocessingml.document

After:

notes.zip -> application/zip
document.docx -> application/vnd.openxmlformats-officedocument.wordprocessingml.document

Demo

Changes

The attachment classifier now inspects ZIP entry names before accepting the DOCX classification. Archives containing the required Word OOXML structure remain DOCX; other valid ZIP containers use application/zip.

The classifier reads only archive metadata. It does not extract archive contents, and inspected bytes remain authoritative over the client-declared media type.

Tests / notes

• ruff format passed.
• ruff check --fix passed.
• git diff --check passed.
• Direct Python 3.13 assertions using the pinned PureMagic 1.30 passed for plain ZIP, DOCX, declared-type mismatches, and malformed ZIP metadata.
• The targeted pytest suite could not run on this Windows host because the locked LiteLLM 1.92.0 dependency requires the MSVC linker (link.exe). CI should run the targeted test under its Linux environment.

AI assistance

Model used: OpenAI GPT-5 through Codex.

Session summary: Codex inspected issue #5620, the attachment classifier, existing unit coverage, and repository contribution conventions. We reproduced that the repository-pinned PureMagic 1.30 classifies both a plain ZIP and a DOCX-shaped archive as DOCX. Codex then helped implement a focused policy that distinguishes DOCX by its internal Word OOXML entries, falls back to application/zip for ordinary ZIP archives, and adds regression coverage for both formats, incorrect client declarations, and malformed archive metadata. I reviewed the resulting diff and validation results before submitting it.

Closes #5620.

[vercel]

@Bharani010 is attempting to deploy a commit to the agenta projects Team on Vercel.

A member of the Team first needs to authorize it.

[CLAassistant]

All committers have signed the CLA.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 508a4f58-52c1-423e-98e9-451a7258722a

📥 Commits

Reviewing files that changed from the base of the PR and between b8712ed and ec0c2f1.

📒 Files selected for processing (2)

• api/oss/src/core/sessions/attachments/media.py
• api/oss/tests/pytest/unit/sessions/test_attachment_media.py

Disabled knowledge base sources:

• Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

---

📝 Walkthrough

Summary by CodeRabbit

• Bug Fixes

  • Improved attachment type detection for ZIP-based files, including DOCX documents.
  • Correctly identifies valid DOCX structures even when the declared file type is inaccurate.
  • Preserves ZIP classification for malformed or invalid archives.

• Tests

  • Expanded coverage for ZIP detection, DOCX recognition, mismatched declarations, and malformed archives.

Walkthrough

The attachment classifier now inspects ZIP contents to distinguish generic ZIP archives from DOCX files. Invalid archives retain their inspected ZIP type. Unit tests cover the new ZIP and DOCX classification cases.

Changes

ZIP media classification

Layer / File(s)	Summary
ZIP container canonicalization api/oss/src/core/sessions/attachments/media.py	The classifier inspects ZIP entries to identify DOCX archives and otherwise uses the generic ZIP type. Invalid ZIP archives retain the inspected type. Optional annotations use str | None.
ZIP classification coverage api/oss/tests/pytest/unit/sessions/test_attachment_media.py	Tests cover plain ZIP files, DOCX structure detection, declared DOCX types with generic ZIP contents, and malformed ZIP signatures.

Estimated code review effort: 2 (Simple) | ~10 minutes

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

✅ Thanks @Bharani010! This PR now meets the contribution requirements and has been reopened. A maintainer will review it soon.