feat: add 4 new features for media reading, auth, and Feishu integration

[YvanJiang]

Summary

This PR introduces 4 new features to enhance CoPaw's functionality:

1. Media Reading Tool (`read_media`)

• Read image, video, and audio files from local paths, file:// URLs, or http(s):// URLs
• Automatic compression for large files to fit model input limits
• Support for image compression (Pillow), video compression with frame extraction (FFmpeg)
• File format validation via magic numbers

2. HTTP Basic Auth Middleware

• Add authentication to protect API endpoints
• Configurable via `config.json` with username, password, and excluded paths
• Compatible with Feishu webhook endpoints (excluded by default)

3. Feishu Webhook Router

• Receive and process Feishu bot webhook events
• Support for signature verification and encryption
• Handle various message types (text, image, post, file)
• Automatic retry mechanism for failed dispatches

4. Feishu Image Message Support

• Card V2 format for rich message display
• Support for sending text and images in a single card
• Better formatting for markdown content

Changes

• New files: `read_media.py`, `auth_middleware.py`, `feishu_webhook.py`, `feishu_notify.py`
• Updated: `feishu/channel.py` with Card V2 support
• Tests included for all new features

Testing

• All pre-commit checks pass
• Unit tests pass (82 tests across 3 test files)
• Code follows project conventions

🤖 Generated with Claude Code

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly expands the system's capabilities by integrating robust media handling, enhancing API security, and deeply integrating with Feishu for richer, more interactive communication. The changes enable the system to process diverse media content, secure its endpoints, and seamlessly interact with Feishu bots through both webhooks and direct notifications, improving overall functionality and user experience.

Highlights

• Media Reading Tool: Introduced a new read_media tool that can read image, video, and audio files from local paths, file:// URLs, or http(s):// URLs. It includes automatic compression for large files and file format validation via magic numbers.
• HTTP Basic Auth Middleware: Added a new FastAPI middleware for HTTP Basic Authentication, allowing protection of API endpoints with configurable username, password, and excluded paths (e.g., for Feishu webhooks).
• Feishu Webhook Router: Implemented a new FastAPI router to receive and process Feishu bot webhook events, supporting signature verification, encryption, and dispatching various message types (text, image, post, file) to the Feishu channel.
• Feishu Image Message Support (Card V2): Enhanced the Feishu channel to support sending and receiving rich messages using the Card V2 format, allowing text and images to be combined within a single message card, and made the Feishu API domain configurable.
• Feishu Notification Router: Added a new FastAPI router to provide a simple HTTP endpoint for sending text notifications to Feishu, which are then processed by the Feishu channel and queued for agent processing.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• src/copaw/agents/tools/init.py
  • Imported and exposed the new read_media tool.
• src/copaw/agents/tools/read_media.py
  • Implemented a new asynchronous tool read_media for reading and processing various media types (image, video, audio).
  • Added support for local files, file:// URLs, and http(s):// URLs.
  • Incorporated automatic compression for images (Pillow) and videos (FFmpeg) to manage file sizes.
  • Included file format validation using magic numbers for enhanced security and reliability.
• src/copaw/app/auth_middleware.py
  • Added a new BasicAuthMiddleware for FastAPI to enforce HTTP Basic Authentication.
  • Provided configuration options for username, password, and paths to be excluded from authentication.
  • Ensured secure credential comparison using secrets.compare_digest.
• src/copaw/app/channels/feishu/channel.py
  • Removed unused imports and added functools.partial for improved function handling.
  • Made the Feishu API domain configurable by adding a domain parameter to the channel initialization.
  • Refactored internal API calls to use the configurable domain instead of hardcoded URLs.
  • Introduced _parse_post_content and _parse_content_row to robustly parse rich text (post) content from Feishu, including embedded images.
  • Updated _on_message to utilize the new post content parsing logic, replacing older extraction methods.
  • Added handle_webhook_event to process incoming Feishu webhook events, converting them into the internal message format.
  • Implemented _build_card_v2_content to construct Feishu Card V2 messages, enabling combined text and image display.
  • Modified _send_text and send_content_parts to leverage the new Card V2 format for sending richer messages, with images uploaded and embedded directly into cards.
• src/copaw/app/routers/feishu_notify.py
  • Added a new FastAPI router for simple Feishu notifications.
  • Enabled sending messages to Feishu via HTTP POST, configurable through environment variables for target chat/user IDs.
  • Implemented logic to parse messages from query parameters or request body.
  • Integrated with FeishuChannel to send direct messages and queue them for agent processing by simulating webhook events.
• src/copaw/app/routers/feishu_webhook.py
  • Implemented a new FastAPI router to handle incoming Feishu webhook events.
  • Included verify_signature and decrypt_body functions for secure processing of webhook payloads, supporting SHA256 signature verification and AES-256-CBC decryption.
  • Provided functionality for URL verification challenges as required by Feishu.
  • Dispatched processed webhook events to the FeishuChannel for further handling.
  • Added a health check endpoint for monitoring the webhook router status.
• tests/channels/test_feishu.py
  • Added comprehensive unit tests for Feishu channel utility functions, message routing, and session ID resolution.
  • Included tests for message deduplication logic and the new _parse_post_content method.
• tests/test_auth_middleware.py
  • Added unit tests for the BasicAuthMiddleware, covering scenarios such as valid/invalid credentials, excluded paths, and disabled authentication.
• tests/test_feishu_webhook.py
  • Added unit tests for the Feishu webhook router, including signature verification, decryption, URL verification, and event dispatching.
  • Included tests for webhook event format conversion and filtering of bot messages.
• tests/tools/test_read_media.py
  • Added comprehensive unit tests for the read_media tool, validating its functionality across various media types and sources.
  • Included tests for error handling, HTTP URL fetching, and image compression capabilities.

Activity

• The pull request introduces several new features and significant refactoring, as detailed in the highlights and changelog.
• There is no human activity recorded on this pull request yet, indicating it's a fresh submission for review.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces several significant new features, including a versatile media reading tool, HTTP Basic Auth middleware, and enhanced Feishu integration with webhook and notification support. The code is generally well-structured and includes comprehensive tests. My review focuses on improving the correctness of file format validation in the new media tool, reducing code duplication, and enhancing maintainability and robustness in a few areas. Overall, this is a substantial and valuable contribution.

_{Note: Security Review is unavailable for this PR.}

[Leirunlin]

@YvanJiang Hi! Thanks again for the PR. We really appreciate the contribution and the new functions here.

While this PR was under review, several related PRs have already been merged: #980, #1009, #1158, and #1159.

Given that this PR introduces many features at once, could you please help with the following:

• Check whether there are still any uncovered parts to keep, and whether some of the functionality here is already covered by the merged PRs. For anything still missing, we’d suggest rebasing on the latest main branch and continuing from there.

• For future contributions, please try to split different features into separate PRs. Smaller PRs are much easier to test and usually get reviewed and merged much faster.

We really appreciate your work and your contribution to the project. At the same time, for PRs that bundle many features together, the review process tends to take longer.

[YvanJiang]

Hi @Leirunlin,

Thanks for the feedback! I've split this PR into 5 smaller, focused PRs as suggested:

1. feat(tools): add read_media tool for image/video/audio processing #1228 - feat(tools): add read_media tool for image/video/audio processing
2. feat(auth): add HTTP Basic Auth middleware for API protection #1229 - feat(auth): add HTTP Basic Auth middleware for API protection
3. feat(feishu): add webhook support with signature verification #1230 - feat(feishu): add webhook support with signature verification
4. feat(feishu): add Card V2 format for rich text+image messages #1231 - feat(feishu): add Card V2 format for rich text+image messages (depends on feat(feishu): add webhook support with signature verification #1230)
5. feat(feishu): add simple HTTP notification endpoint #1232 - feat(feishu): add simple HTTP notification endpoint (depends on feat(feishu): add webhook support with signature verification #1230)

PR #1230, #1231, and #1232 all modify channel.py, so there may be merge conflicts. I've noted the dependencies and suggested merge order in the PR descriptions.

Closing this PR in favor of the new split PRs. Thanks again for the review!