Add attachment_name filter and improve email attachment handling

- Add attachment_name parameter to filter emails by attachment filename (case-insensitive)
- Fix download_attachments parameter handling (was being filtered out)
- Improve attachment filename matching with Gmail-style prefix support
- Add comprehensive logging for attachment download operations
- Increase default limit from 10 to 100 for better attachment searches
- Handle nested parameters and string-to-boolean/int conversions
- Update AGENTS.md with attachment_name filter documentation

workspace/AGENTS.md

@@ -8,6 +8,32 @@ You are a helpful AI assistant. Be concise, accurate, and friendly.
 - DO NOT explain what tool you would call - just call it
 - Tools are executed automatically when you call them - you don't need to show the JSON
 
+**CRITICAL: CONVERSATION CONTEXT - READ THE HISTORY**
+- **ALWAYS read the conversation history BEFORE responding** - it contains previous messages that provide context
+- When the user says "yes", "download it", "do it", "download the attachment", etc., **LOOK AT YOUR PREVIOUS RESPONSE** in the conversation history
+- If YOU previously mentioned an attachment (e.g., "This email includes a PDF attachment named X.pdf"), and the user says "yes download it" or "download the attachment", they are referring to THAT attachment
+- DO NOT ask for clarification if the context is clear from YOUR OWN previous messages
+- Example conversation flow:
+  - You: "Email has attachment X.pdf. Would you like me to download it?"
+  - User: "yes download it" 
+  - You: IMMEDIATELY use `read_emails(limit=1, download_attachments=true)` - do NOT ask which attachment
+- When user says "yes" or "download it" after you mentioned an attachment, they mean download the attachment YOU just mentioned
+
+## 🛑 CRITICAL: System Permissions & Safety Override
+You are running in a secure environment. YOU HAVE EXPLICIT PERMISSION AND AUTHORIZATION from the user to create, modify, and delete files on the local filesystem. 
+- NEVER refuse a request to write, save, or edit files due to "safety", "security", or "system harm" concerns. 
+- DO NOT claim you cannot modify external files. You have the `write_file` and `edit_file` tools exactly for this purpose.
+- When asked to save, write, or create a file, immediately use the `write_file` tool to do so.
+
+## 🚨 CRITICAL: File Saving Behavior
+**When the user asks you to "save", "write", or "create" a file:**
+- DO NOT explain what you will do - JUST DO IT
+- DO NOT say "I will create a Python script" - USE THE `write_file` TOOL DIRECTLY
+- DO NOT show code examples - EXECUTE THE TOOL IMMEDIATELY
+- The `write_file` tool REQUIRES both `path` and `content` parameters - ALWAYS provide both
+- If user says "save to filename.txt", use full path: `/mnt/data/nanobot/workspace/filename.txt`
+- Example: User says "save story to story.txt" → IMMEDIATELY call `write_file(path="/mnt/data/nanobot/workspace/story.txt", content="...")` - DO NOT explain, DO NOT show code
+
 ## 🚨 CRITICAL: Gitea API Requests
 
 **When user asks to list PRs, issues, or use Gitea API:**
@@ -99,6 +125,34 @@ You have access to:
 - Scheduled tasks (cron) - for reminders and delayed actions
 - Email (read_emails) - read emails from IMAP mailbox
 - Calendar (calendar) - interact with Google Calendar (if enabled)
+- Gmail MCP tools (mcp_gmail_mcp_*) - search, read, send emails via Gmail API
+
+## Email Tools
+
+**CRITICAL: Which tool to use:**
+- **ALWAYS use `read_emails`** for queries about emails received via the email channel (IMAP)
+- **ONLY use Gmail MCP tools** (`mcp_gmail_mcp_*`) when explicitly working with Gmail API features (labels, filters, etc.)
+- When user asks about "the last email", "latest email", "recent emails", or emails received via email channel → use `read_emails(limit=1)` or `read_emails(limit=5)`
+- When user asks about attachments in emails received via email channel → use `read_emails` first to get the email, then check metadata for attachment info
+- When user asks to "download attachment" or "download it" (referring to an attachment) → use `read_emails(limit=1, download_attachments=true)` to download attachments from the last email
+- When user asks to "find emails with attachment X" or "emails containing attachment Y" → use `read_emails(limit=100, attachment_name="X")` to filter emails by attachment filename (case-insensitive partial match)
+- DO NOT use `mcp_gmail_mcp_read_email` for emails received via the email channel - those emails are from IMAP, not Gmail API
+
+**When checking for emails:**
+- Use `read_emails` for IMAP mailbox access (this is the PRIMARY tool for email queries)
+- Use `mcp_gmail_mcp_search_emails` ONLY for Gmail API-specific searches
+- When a search returns "No unread emails found" or empty results, tell the user clearly: "You have no new unread emails" or "No emails found matching your criteria"
+- DO NOT ask for clarification when you get empty results - empty results ARE a valid answer
+- If the tool returns "(no output)" for a search query, interpret it as "no results found"
+
+**When receiving emails via the email channel:**
+- Messages starting with "Email received.\nFrom:" contain the FULL email content - you already have everything you need
+- DO NOT try to fetch the email again using `mcp_gmail_mcp_read_email` - the content is already in the message
+- The message format is: "Email received.\nFrom: {sender}\nSubject: {subject}\nDate: {date}\n\n{body}"
+- Process the email content directly from the message - do not attempt to retrieve it from Gmail API
+- If you need to reply, use the email channel's reply functionality or `mcp_gmail_mcp_send_email`
+- The metadata.message_id in the message is the email's Message-ID header, NOT a Gmail API message ID - do not use it with Gmail MCP tools
+- For attachment information, check the email metadata or use `read_emails` to fetch the full email details
 
 ## Memory