feat: support non-image file attachments (download to disk)

[a7351220]

Problem

When a user uploads a non-image, non-audio file (e.g. .txt, .py, .pdf, .json) in Discord, openab silently skips it — the agent never sees the file at all.

Current attachment routing:

• image/* → download + resize + base64 → ACP image content block ✅
• audio/* → STT transcript → text content block ✅
• everything else → skipped ❌

Proposed solution

Download the file to a temp directory on disk and include the path in a text content block. Agents that have file-reading tools (e.g. Claude Code's Read tool) can then access the file contents.

[Attached file: script.py (text/x-python, 1234 bytes) — saved to /tmp/discord-uploads/123456_script.py]

Implementation notes

• Use the existing HTTP_CLIENT for downloading
• Save to /tmp/discord-uploads/{attachment_id}_{sanitized_filename}
• 25 MB size limit (consistent with Discord's upload limit)
• Clean up after prompt completes — collect file paths during download, remove_file after stream_prompt returns
• Return (ContentBlock, PathBuf) from the download function so the caller can track paths for cleanup

Considerations

• This approach is agent-agnostic at the transport level (it's just a text content block), but the agent needs a file-reading tool to actually use it
• Could be gated behind a config flag if not all agent presets benefit from it
• The temp directory is ephemeral (cleared on pod restart), which is fine since files only need to exist during prompt processing

[thepagent]

Have you investigated how OpenClaw and Hermes implemented such feature? And pros and cons? What we can learn from their implementation? Something like #224 with in-depth analysis would be very helpful.

suggested prompt to copy to your AI agent for in-depth analysis:

Analyze https://github.com/openabdev/openab/issues/254 (support non-image file attachments).

Research how these projects handle file attachments from chat platforms:

1. OpenClaw (https://github.com/openclaw/openclaw) — how does it handle non-image, non-audio file attachments from Discord/Telegram? Does it download to disk, inline as text, or skip them?

2. Hermes Agent (https://github.com/NousResearch/hermes-agent) — any file-forwarding capability beyond audio/image?

3. sample-acp-bridge (https://github.com/aws-samples/sample-acp-bridge) — how does it handle arbitrary attachments?

For each project, include:
- Architecture diagram (ASCII flowchart with solid lines)
- Code references with source links
- How files are passed to the downstream agent

Then provide a comparison table:

| Project | Approach | File Types | Size Limit | Cleanup | Security |
|---------|----------|------------|------------|---------|----------|

Analyze security considerations:
- Path traversal / filename sanitization
- Symlink attacks
- Disk exhaustion / size limits
- Untrusted file content execution risk

Finally, recommend the best approach for openab with:
- Pros and cons of each option (download to disk vs inline as text vs hybrid)
- Whether small text files should be inlined directly as ContentBlock::Text
- Proposed config structure
- ASCII architecture diagram of the recommended solution

Format the analysis as a GitHub issue comment. Use the same depth and style as https://github.com/openabdev/openab/issues/224

[CHC-Agent]

Issue at a Glance

Discord User sends file attachment (.txt, .py, .pdf)
        │
        ▼
  discord.rs attachment routing:
        ├─ image/* → base64 → ACP ImageContent ✅
        ├─ audio/* → STT → text ✅
        └─ other   → silently skipped ❌

Hi @a7351220,

This is the remaining piece of #161 (multimodal input). @thepagent has asked for a prior art analysis before moving forward — please follow up in the thread.

[canyugs]

Prior Art Analysis: Non-Image File Attachment Handling

Research requested by @thepagent. Analyzed two mature open-source projects that solve this exact problem (with local code review of cloned repos), plus surveyed the broader ecosystem.

---

1. OpenClaw (openclaw/openclaw)

Approach: Hybrid (inline text + disk offload)

OpenClaw has a full Media Understanding pipeline that routes every attachment type — nothing is silently skipped.

Architecture Diagram

Discord/Telegram attachment
        |
        v
+---------------------------------------+
| fetchWithSsrFGuard()                  |
| (src/infra/net/fetch-guard.ts:267)    |
| - SSRF protection + DNS pinning       |
| - maxBytes enforcement during download |
+---------------------------------------+
        |
        v
+---------------------------------------+
| resolveAttachmentKind()               |
| (src/media-understanding/apply.ts)    |
| - MIME detection + extension fallback  |
+---------------------------------------+
        |
        +------ image/* -------> Vision model describes it (~500 chars)
        |                        OR pass-through if main model has vision
        |
        +------ audio/* -------> Whisper/Deepgram/Groq STT
        |
        +------ video/* -------> Gemini/Moonshot summary (~500 chars)
        |
        +------ text/pdf/code -> extractFileBlocks()
                                 (apply.ts:326)
                                        |
                                        v
                                 +-------------------------------+
                                 | renderFileContextBlock()      |
                                 | (src/media/file-context.ts:27)|
                                 | Wraps in <file> XML tags      |
                                 | Escapes </file> sequences     |
                                 +-------------------------------+
                                        |
                                        v
                                 +-------------------------------+
                                 | wrapUntrustedAttachmentContent|
                                 | (src/security/                |
                                 |  external-content.ts:271)     |
                                 +-------------------------------+
                                        |
                                        v
                              <<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>
                              [extracted text content]
                              Source: External
                              <<<END_EXTERNAL_UNTRUSTED_CONTENT>>>

How Files Are Passed to the Agent

Text/code/PDF content is extracted, wrapped in XML <file name="..." mime="..."> tags, then enclosed in <<<EXTERNAL_UNTRUSTED_CONTENT>>> security boundary markers. The agent sees text, never binary. Images > 2 MB are offloaded to disk (OFFLOAD_THRESHOLD_BYTES in chat-attachments.ts:84).

Code References

File	Purpose
src/media-understanding/apply.ts:326-456	extractFileBlocks() — main routing logic
src/media/file-context.ts:27-49	renderFileContextBlock() — XML wrapping
src/security/external-content.ts:271-297	wrapExternalContent() — untrusted content markers
src/infra/net/fetch-guard.ts:267-430	fetchWithSsrFGuard() — SSRF protection with DNS pinning
src/media/input-files.ts:111-117	Size limit constants
src/media-understanding/attachments.cache.ts:233-241	Session-scoped cache cleanup
src/media/store.ts:115-148	cleanOldMedia() — 2-min TTL background cleanup

Key Numbers

• 5 MB per file (DEFAULT_INPUT_FILE_MAX_BYTES)
• 200K chars max extracted text (DEFAULT_INPUT_FILE_MAX_CHARS)
• 4 pages max for PDFs (DEFAULT_INPUT_PDF_MAX_PAGES)
• 2 MB offload threshold for images to disk
• 2-minute TTL for background media cleanup; session-scoped cleanup in finally block

---

2. Hermes Agent (NousResearch/hermes-agent)

Approach: Download to disk + selective text injection

Hermes downloads all attachments to a local cache directory, then optionally injects small text files inline into the message.

Architecture Diagram

Discord message.attachments
        |
        v
+------------------------------------------+
| _handle_message()                        |
| (gateway/platforms/discord.py:2309)      |
| - Classify by content_type              |
| - Download via aiohttp (30s timeout)     |
+------------------------------------------+
        |
        +------ image/* -----------> cache_image_from_bytes()
        |                            (base.py:257)
        |                            Saved as img_{uuid12}.ext
        |                            -> vision tool reads from disk
        |
        +------ audio/* -----------> cache_audio_from_bytes()
        |                            (base.py:406)
        |                            -> Whisper STT transcription
        |
        +------ document ----------> Check SUPPORTED_DOCUMENT_TYPES
                                     (base.py:510)
                                     {pdf, md, txt, log, zip,
                                      docx, xlsx, pptx}
                                            |
                                            v
                                     +------------------------------+
                                     | cache_document_from_bytes()  |
                                     | (base.py:528)                |
                                     | Saved as:                    |
                                     |   doc_{uuid12}_{sanitized}   |
                                     +------------------------------+
                                            |
                                            v
                                     Is .md/.txt/.log
                                     AND size < 100KB?
                                      /            \
                                    YES             NO
                                    /                \
                                   v                  v
                            Inject inline:      Path only in
                            "[Content of        MessageEvent.media_urls
                             {name}]:\n         (agent uses Read tool)
                             {content}"
                            (discord.py:2439)

How Files Are Passed to the Agent

All files are cached to disk with UUID-prefixed names. For small text files (.md/.txt/.log < 100KB), content is additionally injected inline as [Content of filename.ext]:\n{content}. For everything else, only the disk path is passed via MessageEvent.media_urls.

Code References

File	Purpose
gateway/platforms/discord.py:2309-2456	_handle_message() — attachment classification and download
gateway/platforms/discord.py:2439-2449	MAX_TEXT_INJECT_BYTES (100KB) + inline injection logic
gateway/platforms/base.py:510-525	SUPPORTED_DOCUMENT_TYPES — 8 extensions
gateway/platforms/base.py:528-557	cache_document_from_bytes() — save + path traversal protection
tools/url_safety.py:51	is_safe_url() — SSRF protection (blocks private/CGNAT/metadata IPs)
tools/vision_tools.py:148-162	_ssrf_redirect_guard() — redirect target re-validation
gateway/run.py:8616	Hourly cron calls cleanup_document_cache(max_age_hours=24)

Key Numbers

• 32 MB download limit (MAX_DOC_BYTES)
• 100 KB inline text injection threshold (MAX_TEXT_INJECT_BYTES)
• 8 supported document extensions (pdf, md, txt, log, zip, docx, xlsx, pptx)
• 24-hour TTL for cached files, cleaned hourly via cron
• 30-second HTTP timeout per download

---

3. sample-acp-bridge (aws-samples/sample-acp-bridge)

Text-only. No file attachment handling whatsoever.

Prompt is extracted as plain text (src/agents.py:28) and sent as [{"type": "text", "text": prompt}] (src/acp_client.py:120). The ACP MessagePart model supports content_type fields but the bridge only uses text/plain. No download, caching, or forwarding code exists. No prior art to learn from here.

---

Comparison Table

	OpenClaw	Hermes Agent	sample-acp-bridge	PR #165 (withdrawn)
Approach	Hybrid (inline + disk offload)	Disk + selective inline	Text-only	Disk only
File Types	All (MIME-based routing)	8 extensions	None	All (no filtering)
Text/code handling	Inline with XML + untrusted markers	Inline .md/.txt/.log < 100KB	N/A	Path string only
Binary handling	Disk offload > 2MB	Always disk	N/A	Always disk
Size Limit	5 MB / 200K chars	32 MB download, 100KB inline	N/A	25 MB
Cleanup	Session-scoped + 2-min TTL	24-hour cron	N/A	Session GC
SSRF Protection	DNS pinning + redirect guard	IP blocklist + redirect guard	N/A	None
Path Traversal	N/A (inline-first)	resolve() + is_relative_to()	N/A	Basic sanitize only
Content Security	<<<EXTERNAL_UNTRUSTED_CONTENT>>>	None	N/A	None
Agent Compat.	Any (text injection)	Read tool for large files	N/A	Read tool required

Broader Ecosystem

Project	Approach	Notes
Poe Server Bot Protocol	Hybrid	Platform-level parsed_content for text; raw URL for binary. expand_text_attachments auto-inlines.
claude-code-discord-bridge	Download to disk	Saves to working dir; Claude Code reads via Read tool. Git worktrees per session for isolation.
Claude Discord Bot (VertexAI)	Inline	Reads content, passes directly to Claude API. Images via base64 vision API.

---

Security Considerations

Path Traversal / Filename Sanitization

Discord filenames are user-controlled. Both OpenClaw and Hermes generate their own filenames:

• Hermes: doc_{uuid12}_{sanitized} where sanitized = Path(name).name + strip null bytes + re.sub(r'[^\w.\- ]', '_', name) + post-write resolve().is_relative_to(cache_dir) check
• OpenClaw: uses internal media IDs, original filename only stored as metadata

Recommendation: Generate {uuid}_{sanitized_name} and verify resolved path stays under base dir.

Symlink Attacks

Neither project explicitly guards against symlinks. Mitigations:

• Use mkdtemp() with 0700 permissions (atomic creation)
• Open with O_CREAT | O_EXCL (fail if exists)
• Verify with lstat() that result is regular file, not symlink
• In Rust: std::fs::File::create_new() (stabilized in 1.77) or OpenOptions::new().create_new(true)

Disk Exhaustion

• OpenClaw: 5 MB hard cap + aggressive cleanup (2-min TTL)
• Hermes: 32 MB cap but 24-hour retention = higher risk
• Discord limits uploads to 10 MB (free) / 100 MB (Nitro)

Recommendation: 25 MB per-file cap (match Discord limit), per-session quota, cleanup after stream_prompt returns.

Untrusted File Content Execution

• OpenClaw's approach is best: <<<EXTERNAL_UNTRUSTED_CONTENT>>> markers clearly signal to the LLM that content is external and potentially adversarial. This helps prevent prompt injection via file content.
• Never execute downloaded files or pass them to shells.

Discord CDN URL Expiry

Since late 2023, Discord CDN URLs are signed and expire (~24 hours). Download promptly on message receipt — do not store URLs for later use.

---

Recommended Approach for openab: Hybrid

Both mature projects converged on the same pattern. openab should too.

Architecture Diagram

Discord attachment arrives
        |
        v
+-----------------------------------+
| is_audio_attachment()?            |
+-----------------------------------+
        |                    |
       YES                  NO
        |                    |
        v                    v
  STT (existing)    +-----------------------------------+
                    | is_image_attachment()?             |
                    | (existing download_and_encode_     |
                    |  image logic)                      |
                    +-----------------------------------+
                            |                    |
                           YES                  NO
                            |                    |
                            v                    v
                      base64 encode     +----------------------------+
                      (existing)        | is_text_file(ext, mime)?   |
                                        | AND size < INLINE_THRESHOLD|
                                        +----------------------------+
                                              |              |
                                             YES            NO
                                              |              |
                                              v              v
                                        +-----------+  +-----------------+
                                        | Download  |  | download_to_    |
                                        | bytes,    |  | disk()          |
                                        | decode    |  | /tmp/openab-    |
                                        | UTF-8     |  | attachments/    |
                                        +-----------+  | {thread_id}/    |
                                              |        | {uuid}_{name}   |
                                              v        +-----------------+
                                        ContentBlock         |
                                        ::Text               v
                                                       ContentBlock
                                        "[Attached     ::Text
                                         file: foo.sh
                                         (text/x-sh,  "[Attached file:
                                          1234 B)]     report.pdf
                                         ```sh         (application/pdf,
                                         #!/bin/sh      2.3 MB) -- saved
                                         echo hi        to /tmp/.../
                                         ```"           report.pdf]"

Why Hybrid?

Approach	Pros	Cons
Download to disk only (PR #165)	Simple; handles all types	Requires agent with Read tool; extra round-trip; some agents (Kiro, basic Claude API) can't read files
Inline as text only	Works with any agent; no filesystem risk; immediate context	No binary support; large files blow up token budget; can't handle PDFs/zips
Hybrid (recommended)	Best of both; small text is immediate, large/binary still accessible	Two code paths to maintain (modest complexity)

Small Text Files Should Be Inlined

Yes. For files that are valid UTF-8 and under the threshold:

• Agent sees content immediately without tool calls
• Works with all agent backends (Claude Code, Kiro, Gemini CLI, Codex)
• The 9 KB .sh file from the issue screenshot would be inlined — exactly what the user expected

Proposed Config Structure

[discord.attachments]
# Enable non-image/non-audio attachment handling
enabled = true

# Max file size for disk download (bytes). Files larger are skipped.
max_download_bytes = 26_214_400  # 25 MB

# Max file size for inline text injection (bytes).
# Text files under this threshold are injected directly into the prompt.
# Files above are downloaded to disk with path reference.
text_inline_max_bytes = 65_536  # 64 KB

# Directory for temporary file downloads. Cleaned up after prompt completes.
temp_dir = "/tmp/openab-attachments"

Text extensions for inline detection (compiled into the binary, not user-configurable):
.txt, .md, .sh, .py, .js, .ts, .rs, .go, .java, .rb, .php, .c, .cpp, .h, .css, .html, .xml, .json, .yaml, .yml, .toml, .csv, .log, .env, .sql, .dockerfile

Security Checklist for Implementation

• Sanitize filenames: strip path separators, null bytes, ..; use {uuid}_{sanitized} pattern (Hermes pattern)
• Verify resolved path is under base dir after write (Hermes's is_relative_to() pattern)
• SSRF guard on download URL — block private IP ranges (defense-in-depth; Discord CDN shouldn't redirect there)
• UTF-8 validation for inline text (reject or String::from_utf8_lossy for replacement)
• Cleanup temp files after stream_prompt returns (collect PathBufs during download, remove_dir_all after)
• Use <<<EXTERNAL_UNTRUSTED_CONTENT>>> markers (OpenClaw pattern) to help agents distinguish user text from file content
• Per-file size check before download (use attachment.size from Discord API)

What PR #165 Was Missing

For reference, here's what the withdrawn PR #165 lacked compared to what the prior art shows:

• No SSRF protection on download URLs
• No inline path for small text files (always required agent Read tool round-trip)
• No content security markers for prompt injection defense
• No UTF-8 validation for text content
• Filename sanitization was minimal (no resolve + relative-to check)

---

Sources: Local code review of openclaw/openclaw and NousResearch/hermes-agent. Ecosystem survey via web search (Poe Creator Platform docs, claude-code-discord-bridge, Claude Discord Bot).