feat: File upload support for external channels (Telegram, Slack, public links)

[vybe]

Summary

Enable users to upload files to agents through external channels (Telegram, Slack, public chat links). Files are stored in the agent workspace and the agent is notified via chat message.

Architecture Decisions

Storage Model

• Shared space: All uploads go to /home/developer/uploads/ regardless of user
• Agent instructions (CLAUDE.md) decide how to handle multi-user scenarios
• Metadata preserved: WHO uploaded, WHEN, via WHICH channel

Flow

Channel (Telegram/Slack/Web) 
    → Channel Adapter (download from native API)
    → Backend (validate, audit, store)
    → Agent workspace (/home/developer/uploads/)
    → Inject chat message: "User alice@example.com uploaded report.pdf"

Constraints

• Max file size: 10MB (configurable per-agent later)
• Allowed types: Whitelist — images (png, jpg, gif, webp), documents (pdf, txt, md, csv, json)
• Filename sanitization: Strip path traversal, normalize unicode
• No retention policy v1: Files persist until manually deleted

Acceptance Criteria

Backend

• POST /api/agents/{name}/files/upload endpoint
  • Accepts multipart file upload
  • Validates size, type, filename
  • Stores to agent workspace /home/developer/uploads/{sanitized_filename}
  • Returns file path and metadata
• Audit trail: file_uploads table or entries in audit_log
  • agent_name, filename, file_size, mime_type
  • uploaded_by_email, channel (telegram/slack/web/api)
  • timestamp, file_path

Channel Adapters

• Extend ChannelAdapter ABC with download_file(file_ref) -> (bytes, metadata)
• Telegram adapter: Download via Bot API getFile + file path
• Slack adapter: Download via Files API with bot token
• After storing, inject system message into chat stream

Agent Integration

• Chat message format: [File uploaded by {email}]: {filename} ({size}) saved to /uploads/{filename}
• Agent can read via standard file tools

Security

• MIME type validation (magic bytes, not just extension)
• Filename sanitization (no .., no /, truncate length)
• Size limit enforced before full read

Out of Scope (v1)

• Per-user namespaced folders
• Storage quotas
• Automatic cleanup/retention
• Virus scanning
• Image/document preview in UI

Related

• Depends on channel adapter infrastructure (SLACK-002, Telegram adapter)
• Audit log infrastructure (SEC-001)