feat: add file/image attachment support to WASM channels

[sergeytimoshin]

Enable the agent to download files via the http tool and send them as attachments through WASM channels (photos on Telegram, documents elsewhere).

Changes:

• WIT: add attachment record, extend agent-response, add on-broadcast export
• WASM wrapper: wire attachments through respond/broadcast, read files from disk, detect MIME types, enforce 50MB size cap
• Telegram: implement multipart file upload (sendPhoto/sendDocument), support attachments in on_respond and on_broadcast, add polling_enabled config flag, reduce poll timeout to 25s to avoid WASM callback race
• HTTP tool: add save_to parameter for binary file downloads to /tmp, allow redirects (up to 10 hops) instead of blocking 3xx responses
• Message tool: allow attachment paths from /tmp in addition to sandbox dir, update description to document the download-then-attach workflow
• Credentials: fall back to environment variables when secrets store has no matching entry for a channel credential
• Discord/Slack/WhatsApp: add stub on_broadcast implementations

[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 agent's communication capabilities by integrating file and image attachment support across WASM channels. It enables agents to download files using the HTTP tool and subsequently send them as attachments through various channels, with specific implementations for Telegram. The changes also improve credential management by allowing environment variable fallbacks and refine HTTP request handling.

Highlights

• File and Image Attachment Support: Introduced comprehensive file and image attachment support for WASM channels, allowing agents to send various media types through on_respond and the new on_broadcast functions.
• Telegram Channel Enhancements: Enhanced the Telegram channel to handle multipart file uploads (photos and documents), support attachments in on_respond and on_broadcast, added a polling_enabled configuration option, and reduced the poll timeout to 25 seconds.
• HTTP Tool Updates: Updated the HTTP tool with a save_to parameter for downloading binary files to /tmp and enabled automatic redirection following for up to 10 hops, removing the previous redirect blocking.
• Message Tool Flexibility: Modified the Message tool to permit attachment paths from the /tmp directory, alongside existing sandbox paths, facilitating a download-then-attach workflow.
• Credential Management Improvement: Implemented a fallback mechanism for channel credentials, allowing them to be sourced from environment variables if not found in the secrets store.
• WASM Channel Interface Extension: Extended the WASM channel interface (wit/channel.wit) with an attachment record and an on-broadcast export, and wired these through the WASM wrapper to enable proactive messages with attachments.

Changelog

• Cargo.lock
  • Added console package.
  • Updated syn dependency to version 2.0.117.
• channels-src/discord/src/lib.rs
  • Added a stub implementation for the on_broadcast function.
• channels-src/slack/src/lib.rs
  • Added a stub implementation for the on_broadcast function.
• channels-src/telegram/src/lib.rs
  • Imported the Attachment type from the channel WIT interface.
  • Introduced a polling_enabled flag to the TelegramConfig struct.
  • Adjusted the webhook mode logic to prioritize polling_enabled over tunnel_url presence.
  • Reduced the get_updates_url poll timeout from 30s to 25s.
  • Modified on_respond to send attachments before text content.
  • Implemented the on_broadcast function to send messages with attachments.
  • Added helper functions write_multipart_field, write_multipart_file, send_photo, send_document, and send_attachment for handling multipart file uploads to Telegram.
• channels-src/whatsapp/src/lib.rs
  • Added a stub implementation for the on_broadcast function.
• src/channels/wasm/wrapper.rs
  • Updated the call_on_respond function signature to include an attachments parameter.
  • Modified call_on_respond to read attachment files from disk before passing them to WASM.
  • Implemented the call_on_broadcast function, including reading attachments from disk.
  • Updated the Channel trait implementation for send and broadcast to pass attachment paths.
  • Added mime_from_extension to determine MIME types from file extensions.
  • Defined MAX_TOTAL_ATTACHMENT_BYTES for attachment size limits.
  • Included a test for mime_from_extension.
• src/main.rs
  • Updated inject_channel_credentials to fall back to environment variables for credentials not found in the secrets store.
• src/tools/builtin/http.rs
  • Configured the HTTP client to follow up to 10 redirects.
  • Updated the tool description to explain the save_to parameter for binary downloads.
  • Added save_to to the parameters schema, requiring paths under /tmp/.
  • Removed the explicit blocking of 3xx redirects.
  • Implemented logic to save the HTTP response body to a specified file path.
• src/tools/builtin/message.rs
  • Updated the tool description to document the download-then-attach workflow for attachments.
  • Modified attachment path validation to allow files located in /tmp/ in addition to the sandbox directory.
  • Adjusted a test case to reflect the updated attachment path validation rules.
• wit/channel.wit
  • Defined a new attachment record with filename, mime-type, and data fields.
  • Extended the agent-response record to include a list of attachment records.
  • Added a new on-broadcast function export to the channel interface.

Activity

• No human activity has been recorded on this pull request yet.

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 Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, 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 file and image attachment support for WASM channels. However, critical security vulnerabilities have been identified, including a path traversal vulnerability in the HttpTool allowing arbitrary file writes, SSRF attacks due to automatic redirect following without re-validation, and a multipart header injection flaw in the Telegram channel's attachment handling. Additionally, while several code duplication issues were noted, these refactorings are suggested to be deferred to follow-up tasks to maintain focus on the current feature implementation. A suggestion to improve MIME type detection by utilizing the mime_guess crate is also included.

I am having trouble creating individual review comments. Click here to see my feedback.

src/tools/builtin/http.rs (410-416)

The HttpTool introduces a save_to parameter that allows saving the response body to a file. The validation check !save_to.starts_with("/tmp/") is insufficient to prevent path traversal attacks. An attacker (e.g., via prompt injection) can provide a path like /tmp/../../etc/passwd which starts with /tmp/ but resolves to a location outside the intended directory. This allows overwriting arbitrary files on the host system with content fetched from a URL.

src/tools/builtin/http.rs (40)

The HttpTool was modified to follow redirects automatically (up to 10 hops). While the initial URL is validated against a blocklist of private IPs and localhost in validate_url, subsequent URLs in a redirect chain are not re-validated. An attacker can provide a URL that points to a malicious server, which then redirects the client to a sensitive internal resource (e.g., https://127.0.0.1/admin or cloud metadata services), bypassing the SSRF protections.

channels-src/telegram/src/lib.rs (892-896)

The write_multipart_file function constructs a Content-Disposition header by directly embedding the filename without sanitization or escaping. The filename is derived from the file path provided in the tool parameters. If a filename contains double quotes or newline characters, an attacker can inject additional parameters or headers into the multipart request.

channels-src/telegram/src/lib.rs (654-679)

The logic in on_broadcast for sending attachments and then the message content is very similar to the logic in on_respond. This duplication can be refactored into a shared helper function to improve maintainability. However, for this feature-focused PR, consider tracking this refactoring as a follow-up task.

References

1. Consolidate related sequences of operations, such as creating, persisting, and scheduling a job, into a single reusable method to improve code consistency and maintainability.
2. Defer large structural refactorings, like breaking down a large file, when the primary goal of a pull request is to achieve correctness and feature parity with an existing implementation. The refactoring should be tracked as a follow-up task.

channels-src/telegram/src/lib.rs (906-1013)

The functions send_photo and send_document are nearly identical. This duplicated code can be extracted into a single helper function to reduce redundancy and improve maintainability. For this feature-focused PR, consider tracking this refactoring as a follow-up task.

References

1. Consolidate related sequences of operations, such as creating, persisting, and scheduling a job, into a single reusable method to improve code consistency and maintainability.
2. Defer large structural refactorings, like breaking down a large file, when the primary goal of a pull request is to achieve correctness and feature parity with an existing implementation. The refactoring should be tracked as a follow-up task.

src/channels/wasm/wrapper.rs (1254-1363)

This new call_on_broadcast function is almost a complete copy of call_on_respond, introducing significant duplicated code. While refactoring this common logic into a generic execute_wasm_callback helper function would drastically reduce duplication and improve maintainability, for this feature-focused PR, it is recommended to track this as a follow-up task.

References

1. Consolidate related sequences of operations, such as creating, persisting, and scheduling a job, into a single reusable method to improve code consistency and maintainability.
2. Defer large structural refactorings, like breaking down a large file, when the primary goal of a pull request is to achieve correctness and feature parity with an existing implementation. The refactoring should be tracked as a follow-up task.

src/channels/wasm/wrapper.rs (2517-2555)

This manual implementation for detecting MIME types from file extensions is quite extensive and could be hard to maintain. The mime_guess crate is already a dependency in the project and provides a more robust and comprehensive way to handle this.

Using mime_guess would simplify this code and ensure you're using a standard, well-maintained library for MIME detection.

fn mime_from_extension(path: &str) -> String {
    mime_guess::from_path(path)
        .first_or_octet_stream()
        .to_string()
}

[Copilot]

Pull request overview

Adds end-to-end support for downloading files and sending them as attachments through WASM-backed channels (with Telegram implementing real uploads and other channels adding scaffolding).

Changes:

• Extend channel WIT types to include attachment records on agent-response and add an on-broadcast export for proactive sends.
• Wire attachment paths through the Rust host WASM wrapper (read files, infer MIME types, enforce a total size cap) and expose broadcast behavior.
• Update built-in tools and channels: HTTP tool adds save_to downloads and redirect following; Message tool allows /tmp attachments; Telegram adds multipart uploads; other WASM channels stub on_broadcast.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
wit/channel.wit	Adds attachment type + attachments on responses + on-broadcast callback definition.
src/tools/builtin/message.rs	Documents download→attach flow; allows attachment paths from /tmp as well as base dir; updates tests.
src/tools/builtin/http.rs	Enables redirects and adds save_to to write response bytes to disk.
src/main.rs	Adds env-var fallback when injecting channel credentials.
src/channels/wasm/wrapper.rs	Reads attachment files into WIT attachments, adds call_on_broadcast and Channel broadcast, adds MIME helper.
channels-src/telegram/src/lib.rs	Supports attachments by multipart upload via sendPhoto/sendDocument; adds polling_enabled; adjusts poll timeout.
channels-src/whatsapp/src/lib.rs	Adds stub on_broadcast.
channels-src/slack/src/lib.rs	Adds stub on_broadcast.
channels-src/discord/src/lib.rs	Adds stub on_broadcast.
Cargo.lock	Updates dependency lockfile to include new/updated crates.

Comments suppressed due to low confidence (3)

src/channels/wasm/wrapper.rs:2578

• read_attachments reads each entire file into memory (std::fs::read) before enforcing the 50MB total size cap. A single oversized file can cause large allocations / OOM before you ever hit the limit check. Consider pre-checking sizes via metadata().len() (and/or streaming reads with an upper bound) before loading bytes into memory.

            extension_name,
            success,
            message,
        } => wit_channel::StatusUpdate {
            status: wit_channel::StatusType::AuthCompleted,
            message: format!(
                "Authentication {} for {}. {}",
                if *success { "completed" } else { "failed" },
                extension_name,
                message
            ),

src/channels/wasm/wrapper.rs:2571

• read_attachments reads arbitrary host filesystem paths provided via OutgoingResponse.attachments without any sandbox/allowlist validation. This means any caller that can influence attachments could exfiltrate local files through the WASM channel. Consider validating attachment paths here as a defense-in-depth measure (e.g., restrict to ironclaw_base_dir() and /tmp using path_utils::validate_path).

            extension_name,
            success,
            message,
        } => wit_channel::StatusUpdate {

src/tools/builtin/http.rs:370

• The comment about still seeing a 3xx status meaning the redirect chain was too long is inaccurate with Policy::limited(...) (reqwest errors on too many redirects rather than returning a final 3xx). Also 3xx statuses like 304 aren’t redirects. Either explicitly handle 3xx responses here (with a clear error) or adjust the comment to reflect actual behavior.

        let status = response.status().as_u16();

        // Redirects are followed automatically (up to 10 hops).
        // If we still see a 3xx here, the chain was too long.

        let headers: HashMap<String, String> = response
            .headers()
            .iter()
            .filter_map(|(k, v)| v.to_str().ok().map(|v| (k.to_string(), v.to_string())))
            .collect();

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

Comments suppressed due to low confidence (4)

src/channels/wasm/wrapper.rs:2676

• read_attachments accepts arbitrary filesystem paths and calls std::fs::read directly. Since attachments can be set by the agent/tooling, this creates a local file read primitive unless paths are validated at a single choke point. Consider validating each path with the same sandbox rules as MessageTool (e.g., only under ~/.ironclaw and/or a dedicated /tmp/ironclaw download dir) before reading.

    use crate::channels::wasm::runtime::{
        PreparedChannelModule, WasmChannelRuntime, WasmChannelRuntimeConfig,
    };
    use crate::channels::wasm::wrapper::{HttpResponse, WasmChannel};

src/channels/wasm/wrapper.rs:2278

• impl Channel for WasmChannel now contains two broadcast methods (one earlier that ignores user_id and calls call_on_respond, and this new one calling call_on_broadcast). This will not compile and also leaves a stale broadcast path that doesn't pass the new attachments arg to call_on_respond.

    }

    async fn shutdown(&self) -> Result<(), ChannelError> {
        // Cancel typing indicator
        self.cancel_typing_task().await;

        // Send shutdown signal
        if let Some(tx) = self.shutdown_tx.write().await.take() {
            let _ = tx.send(());
        }

        // Stop polling by dropping the sender (receiver will complete)

src/channels/wasm/wrapper.rs:2403

• impl Channel for SharedWasmChannel defines broadcast twice, which will not compile. Keep only one implementation that forwards to inner.broadcast(...).

                },
            )
            .collect(),
        poll: wit
            .poll
            .map(|p| crate::channels::wasm::schema::PollConfigSchema {
                interval_ms: p.interval_ms,

src/channels/wasm/wrapper.rs:2683

• read_attachments reads the entire file into memory before enforcing MAX_TOTAL_ATTACHMENT_BYTES, so a single large file can temporarily allocate far beyond the limit (and potentially OOM) even though it later errors. Consider checking std::fs::metadata(path)?.len() (and running total) before reading, or reading with an upper bound.

    use crate::channels::wasm::runtime::{
        PreparedChannelModule, WasmChannelRuntime, WasmChannelRuntimeConfig,
    };
    use crate::channels::wasm::wrapper::{HttpResponse, WasmChannel};
    use crate::pairing::PairingStore;
    use crate::tools::wasm::ResourceLimits;

    fn create_test_channel() -> WasmChannel {
        let config = WasmChannelRuntimeConfig::for_testing();
        let runtime = Arc::new(WasmChannelRuntime::new(config).unwrap());

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[zmanian]

Good feature idea -- attachment support through WASM channels is needed. The Telegram multipart implementation and WIT interface extensions show solid understanding of the system. However, there are several security issues that need to be addressed before merge.

Critical

1. create_dir_all before path validation (TOCTOU in validate_save_to_path).
In src/tools/builtin/http.rs, create_dir_all(parent) is called before validate_path. A path like /tmp/../../var/evil/ passes the starts_with("/tmp/") prefix check, then create_dir_all creates directories outside /tmp before validate_path rejects it. Move create_dir_all after validation succeeds.

2. WIT breaking changes with no backward compatibility strategy.
Adding attachments to agent-response and the new on-broadcast export are breaking changes. Pre-compiled WASM channels that don't export on-broadcast will fail to instantiate. Consider making on-broadcast optional in the WIT world, or detect its absence and fall back gracefully. At minimum, document this as a breaking WIT change.

High

3. SSRF redirect policy fails open on DNS resolution failure.
In the custom redirect policy in http.rs, when to_socket_addrs() returns Err, the redirect is allowed (attempt.follow()). Fail-closed: reject redirects when DNS resolution fails.

4. read_attachments has no path validation (defense-in-depth).
In src/channels/wasm/wrapper.rs, read_attachments reads arbitrary file paths with no validation. While the message tool validates paths upstream, defense-in-depth requires read_attachments to independently validate paths are within allowed directories (/tmp or sandbox base dir).

5. Credential env-var fallback should be a separate PR.
The inject_channel_credentials change in main.rs bypasses the encrypted secrets store for env var fallback. This is orthogonal to attachments and has security implications (credentials visible in /proc/<pid>/environ). Split this out.

Medium

6. Stub on_broadcast returns Ok(()) on silent message drop.
Discord/Slack/WhatsApp stubs return Ok(()), telling the caller delivery succeeded when the message was actually dropped. Return Err("Broadcast not implemented for this channel") instead.

7. Predictable multipart boundary.
format!("ironclaw-{}", channel_host::now_millis()) is predictable. If the boundary appears in attachment data, the multipart message will be malformed. Use a random or hash-based boundary.

8. Unrelated polling_enabled change bundled in.
The polling_enabled config flag and poll timeout change (30s to 25s) in the Telegram channel are unrelated to attachments. Separate commit or PR.

Low

• content_type not sanitized in multipart headers (header injection if \r\n present)
• 50 MB fully buffered in memory before disk write -- consider streaming for large files
• Code duplication between Telegram on_respond and on_broadcast for attachment sending

Nice first contribution -- the overall architecture is right. Please fix the security items and split the credential fallback into its own PR.

[ilblackdragon]

All features from #409 are on main:

• WIT attachment record and on-broadcast export
• read_attachments() and call_on_broadcast() in wrapper.rs
• Telegram send_photo/send_document multipart upload
• HTTP tool save_to parameter with redirect following
• Message tool /tmp attachment paths
• Credential env var fallback
• Discord/Slack/WhatsApp on_broadcast stubs