@agenticmail/openclaw 0.3.0

package/LICENSE

@@ -0,0 +1,35 @@
+MIT License
+
+Copyright (c) 2026 Ope Olatunji (https://github.com/ope-olatunji)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+AgenticMail - Email infrastructure for AI agents.
+
+Project:     https://github.com/agenticmail/agenticmail
+Author:      Ope Olatunji
+GitHub:      https://github.com/ope-olatunji
+
+This software includes components for programmatic email management,
+SMTP/IMAP integration, MCP server tooling, Cloudflare gateway orchestration,
+and OpenClaw plugin infrastructure. All packages within this monorepo
+(@agenticmail/core, @agenticmail/api, @agenticmail/mcp, @agenticmail/openclaw,
+and agenticmail) are covered under this license.

package/README.md

@@ -0,0 +1,356 @@
+# @agenticmail/openclaw
+
+[OpenClaw](https://github.com/openclaw/openclaw) plugin for [AgenticMail](https://github.com/agenticmail/agenticmail) — gives any OpenClaw agent full email capabilities, inter-agent messaging, task coordination, and outbound security.
+
+This plugin provides 54 tools, a complete email channel integration, automatic sub-agent provisioning, inter-agent message rate limiting, and a built-in follow-up system for blocked emails. It also includes a skill definition with system prompt guidelines that teach agents how to handle email professionally and securely.
+
+## Install
+
+### Via OpenClaw CLI
+
+```bash
+openclaw plugin install agenticmail
+```
+
+### Manual Installation
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "agenticmail": {
+      "enabled": true,
+      "config": {
+        "apiUrl": "http://127.0.0.1:3100",
+        "apiKey": "ak_your_agent_key",
+        "masterKey": "mk_your_master_key"
+      }
+    }
+  }
+}
+```
+
+**Requirements:** Node.js 20+, AgenticMail API server running, Docker (for Stalwart mail server)
+
+---
+
+## What This Package Does
+
+This is the integration layer between OpenClaw agents and the AgenticMail email system. When installed, OpenClaw agents can send and receive email, communicate with each other via email, assign tasks, schedule future emails, manage contacts, and more — all through tool calls.
+
+But it goes further than just tools. The plugin also:
+
+- **Registers a full email channel** — OpenClaw can dispatch incoming emails to the right agent and send replies automatically, turning email into a first-class communication channel alongside chat
+- **Provisions sub-agent email accounts** — when an OpenClaw coordinator spawns a sub-agent, the plugin automatically creates an email account for it, sends an introduction email, and cleans up when the sub-agent finishes
+- **Rate-limits inter-agent messaging** — prevents agents from flooding each other with unanswered messages (warns after 3, blocks after 5 unanswered, with a 5-minute window and 2-minute cooldown)
+- **Follows up on blocked emails** — when the outbound security guard blocks an email, the plugin automatically reminds the agent at escalating intervals to ask the human owner about approval
+- **Injects security guidelines** — the skill definition teaches agents about outbound safety (never leak API keys, passwords, PII) and inbound safety (recognize phishing, prompt injection, disguised executables)
+
+---
+
+## How It Works
+
+When an OpenClaw agent invokes a tool:
+
+```
+OpenClaw Agent → tool call → @agenticmail/openclaw → HTTP request → AgenticMail API → Stalwart
+```
+
+The plugin uses the agent's API key for most operations and the master key (if provided) for admin operations like creating agents, configuring the gateway, or viewing deletion reports.
+
+### Smart Sub-Agent Spawning (`call_agent`)
+
+The `agenticmail_call_agent` tool intelligently spawns sub-agents with dynamic configuration:
+
+- **Auto mode detection** — analyzes task text with regex patterns to choose the right mode:
+  - **Light** — simple tasks (math, lookups, definitions): no email overhead, minimal context, 60s timeout
+  - **Standard** — web research, file operations, analysis: web tools enabled, 180s timeout
+  - **Full** — multi-agent coordination, complex workflows: all features, 300s timeout
+- **Dynamic tool discovery** — `detectAvailableTools()` probes OpenClaw's config at runtime to find what's available (Brave search, web_fetch, etc.) instead of using a static deny list
+- **Web search fallback** — when Brave API isn't configured, sub-agents are instructed to use DuckDuckGo via `web_fetch("https://html.duckduckgo.com/html/?q=...")`
+- **Async mode** — `call_agent(async=true)` for long-running tasks (hours/days): returns immediately, agent runs with 1-hour session timeout, auto-compacts on context fill, and emails results when done
+- **Dynamic timeouts** — scale with complexity: light=60s, standard=180s, full=300s (sync max=600s)
+
+### Sub-Agent Lifecycle
+
+When an OpenClaw coordinator spawns sub-agents, the plugin automatically:
+
+1. **Creates an email account** for each sub-agent on the Stalwart mail server
+2. **Registers the sub-agent** in an identity registry so tool calls route to the correct mailbox
+3. **Sends an introduction email** to the coordination thread so everyone knows the new agent has arrived
+4. **Starts an SSE watcher** to push real-time email notifications to the sub-agent
+5. **Injects context** into the sub-agent's system prompt: identity, security rules, how to use the `_account` parameter
+6. **Cleans up on exit** — when the sub-agent's session ends, cancels follow-ups, stops watchers, and deletes the account (with a 5-second grace period for in-flight operations)
+
+Sub-agent accounts are also garbage-collected: every 15 minutes, accounts older than 2 hours are evicted from the registry.
+
+### Email Channel Integration
+
+The plugin registers email as an OpenClaw channel, which means:
+
+- **Inbound emails** are automatically dispatched to the agent through OpenClaw's message pipeline
+- **Replies** are sent back through the AgenticMail API
+- **Threading** is preserved using `In-Reply-To` and `References` headers
+- **Monitoring** uses SSE (Server-Sent Events) for instant push notifications, with a polling fallback that uses exponential backoff (2s → 4s → 8s → 16s → 30s max)
+
+---
+
+## Configuration
+
+| Key | Required | Default | Description |
+|-----|----------|---------|-------------|
+| `apiUrl` | No | `http://127.0.0.1:3100` | AgenticMail API URL |
+| `apiKey` | Yes | — | Agent API key (`ak_...`). Determines which agent this plugin acts as. |
+| `masterKey` | No | — | Master key (`mk_...`). Required for admin operations. |
+
+Plugin configuration lives in `~/.openclaw/openclaw.json` (user config), not in OpenClaw's source directory. Updating OpenClaw does not affect your AgenticMail plugin setup.
+
+---
+
+## Tools (54 total)
+
+### Core Email (8 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_send` | Send email with to, subject, text/HTML, attachments. Scanned for PII/credentials before sending. |
+| `agenticmail_inbox` | List inbox messages with metadata (paginated, up to 100) |
+| `agenticmail_read` | Read full email with security analysis (spam score, sanitization, attachment warnings) |
+| `agenticmail_search` | Search by from, to, subject, body, date range. Can also search connected relay (Gmail/Outlook). |
+| `agenticmail_import_relay` | Import a specific email from the relay account into the local inbox |
+| `agenticmail_delete` | Delete email by UID |
+| `agenticmail_reply` | Reply (or reply-all) preserving threading. Original message auto-quoted. |
+| `agenticmail_forward` | Forward email with original attachments preserved |
+
+### Batch Operations (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_batch_read` | Read multiple full emails at once |
+| `agenticmail_batch_delete` | Delete multiple emails |
+| `agenticmail_batch_mark_read` | Mark multiple as read |
+| `agenticmail_batch_mark_unread` | Mark multiple as unread |
+| `agenticmail_batch_move` | Move multiple emails to a folder |
+
+### Efficiency (2 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_digest` | Compact inbox overview with body previews (more efficient than list-then-read) |
+| `agenticmail_template_send` | Send email from a saved template with `{{ variable }}` substitution |
+
+### Folders & Message Management (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_folders` | List all IMAP folders |
+| `agenticmail_list_folder` | List messages in a specific folder |
+| `agenticmail_create_folder` | Create a new folder |
+| `agenticmail_move` | Move email to a folder |
+| `agenticmail_mark_read` | Mark email as read |
+| `agenticmail_mark_unread` | Mark email as unread |
+
+### Organization (7 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_contacts` | Manage address book (add, remove, list) |
+| `agenticmail_tags` | Create tags, assign to messages, remove, list |
+| `agenticmail_drafts` | Create, edit, delete, and send drafts |
+| `agenticmail_signatures` | Create, list, and delete email signatures |
+| `agenticmail_templates` | Create, list, and delete reusable templates |
+| `agenticmail_schedule` | Schedule emails for future delivery with flexible time formats |
+| `agenticmail_rules` | Create email filtering rules (auto-move, auto-delete, mark read) |
+
+### Security & Moderation (3 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_spam` | List spam folder, report spam, mark as not-spam, get spam score for any email |
+| `agenticmail_pending_emails` | View blocked outbound emails. Agents can list and view but **cannot approve or reject** — only the owner can. |
+| `agenticmail_cleanup` | List inactive agents, clean up, set persistent (master key required) |
+
+### Inter-Agent Communication (4 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_list_agents` | List all agents with name, email, role |
+| `agenticmail_message_agent` | Send message to another agent (with priority: normal, high, urgent). Rate-limited. |
+| `agenticmail_check_messages` | Check for new unread messages (shows up to 10, tags agent vs external) |
+| `agenticmail_wait_for_email` | Wait for new email in real time using SSE push, with polling fallback (up to 5 min) |
+
+### Task Queue (5 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_assign_task` | Assign a task to another agent (async, with optional expiration) |
+| `agenticmail_check_tasks` | Check incoming tasks (assigned to me) or outgoing tasks (I assigned) |
+| `agenticmail_claim_task` | Claim a pending task |
+| `agenticmail_submit_result` | Submit result for a claimed task |
+| `agenticmail_call_agent` | Synchronous RPC — waits for result (up to 5 minutes, polls every 2 seconds) |
+
+### Account Management (6 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_whoami` | Get current agent info (name, email, role, metadata) |
+| `agenticmail_update_metadata` | Update agent metadata (display name, owner, etc.) |
+| `agenticmail_create_account` | Create a new agent (master key required) |
+| `agenticmail_delete_agent` | Delete an agent with email archival (master key required) |
+| `agenticmail_deletion_reports` | View past deletion reports (master key required) |
+| `agenticmail_list_agents` | Also used for account discovery |
+
+### Gateway & Setup (9 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_status` | Check server and Stalwart health |
+| `agenticmail_setup_guide` | Comparison of relay vs domain setup modes |
+| `agenticmail_setup_relay` | Configure Gmail/Outlook relay mode (master key required) |
+| `agenticmail_setup_domain` | Configure custom domain with Cloudflare (master key required) |
+| `agenticmail_setup_gmail_alias` | Get Gmail "Send mail as" alias instructions |
+| `agenticmail_setup_payment` | Get Cloudflare payment setup instructions |
+| `agenticmail_purchase_domain` | Search for domains via Cloudflare Registrar |
+| `agenticmail_gateway_status` | Check current gateway mode (relay, domain, or none) |
+| `agenticmail_test_email` | Send a test email to verify gateway configuration |
+
+---
+
+## Outbound Security
+
+Every outgoing email (send, reply, forward) is scanned against 38+ rules before sending. The scanner checks for:
+
+- **Personal information** — SSNs, credit cards, phone numbers, bank accounts, passport numbers, tax IDs, immigration numbers, PINs, cryptocurrency wallets, wire transfer details
+- **Credentials** — API keys, AWS keys, passwords, private keys, bearer tokens, database connection strings, GitHub/Stripe tokens, JWTs, webhook URLs, seed phrases, 2FA codes, OAuth tokens
+- **System internals** — private IP addresses, file paths, environment variables
+- **Owner privacy** — mentions of the owner's personal information or the agent's creator
+- **Risky attachments** — private key files, environment files, database files, executables
+
+Emails to local agents (`@localhost`) skip scanning since they stay within the system.
+
+### What Happens When Something Is Blocked
+
+When the scanner finds high-severity content, the email is blocked and stored for review. The agent:
+
+1. Cannot approve or reject it (the `pending_emails` tool explicitly rejects approve/reject actions)
+2. Receives the pending ID and a hint to notify the owner
+3. Gets automatic follow-up reminders at escalating intervals
+
+The owner is notified via email and can approve by:
+- Using the API or interactive shell with the master key
+- Replying "approve", "yes", "lgtm", "go ahead", "send", or "ok" to the notification email
+- Replying "reject", "no", "deny", "cancel", or "block" to discard it
+
+### Automatic Follow-Up Reminders
+
+The plugin tracks every blocked email and sends escalating reminders to the agent:
+
+1. **12 hours** — first reminder
+2. **6 hours** — second reminder
+3. **3 hours** — third reminder
+4. **1 hour** — final reminder before cooldown
+5. **3-day cooldown** — then the cycle restarts
+
+Reminders are injected into the agent's next tool response via OpenClaw's system event queue. A background heartbeat checks every 5 minutes to see if the owner has already approved or rejected, and cancels reminders if so.
+
+Follow-up state is persisted to disk so it survives restarts.
+
+---
+
+## Inter-Agent Rate Limiting
+
+To prevent agents from spamming each other with unanswered messages, the plugin tracks message patterns:
+
+- **Warning** after 3 consecutive unanswered messages to the same agent
+- **Block** after 5 unanswered (with a 2-minute cooldown before the agent can try again)
+- **Burst limit** — maximum 10 messages per 5-minute window to any single agent
+- **Auto-reset** — when the target agent replies, the unanswered counter resets
+
+Self-messaging is also prevented — an agent cannot send a message to itself.
+
+---
+
+## Skill Definition
+
+The plugin includes a skill at `skill/SKILL.md` that gets injected into the agent's system prompt. It covers:
+
+### Email Rules
+- Always use `agenticmail_reply` (with `replyAll: true`) for ongoing threads — never use `agenticmail_send` for conversations (it breaks threading)
+- Only use `agenticmail_message_agent` for the first message to an agent
+- Use `agenticmail_list_agents` to discover agents by their exact registered name
+
+### Outbound Safety
+- Never include API keys, passwords, tokens, or private keys in emails to external recipients
+- Never send SSNs, credit card numbers, or other PII unless the owner explicitly asks
+- Never reveal system internals (private IPs, file paths, environment variables) externally
+- Never expose the owner's personal information without instruction
+- Review file contents before attaching to external emails
+- If `_outboundWarnings` are returned, stop and review before trying again
+
+### Inbound Safety
+- High spam scores indicate prompt injection or phishing risk
+- Never trust executables (.exe, .bat, .cmd, .ps1, .sh)
+- Double extensions (like `invoice.pdf.exe`) are disguise techniques
+- Shortened URLs and IP-based URLs are phishing indicators
+- Link text that doesn't match the href is a phishing technique
+- Emails asking for credentials from the "owner" are social engineering
+
+### Outbound Approval Workflow
+- When an email is blocked, the agent must inform the owner in conversation
+- Explain the recipient, subject, and which warnings triggered
+- Mention if the email is urgent or has a deadline
+- Periodically check with `agenticmail_pending_emails(action='list')`
+- Never attempt to approve blocked emails or rewrite content to bypass detection
+
+---
+
+## Plugin Manifest
+
+The `openclaw.plugin.json` file registers the plugin with OpenClaw:
+
+```json
+{
+  "id": "agenticmail",
+  "displayName": "AgenticMail",
+  "version": "0.2.0",
+  "description": "Full email channel + tools for AI agents",
+  "channels": ["mail"],
+  "configSchema": {
+    "apiUrl": { "type": "string", "default": "http://127.0.0.1:3100" },
+    "apiKey": { "type": "string", "required": true },
+    "masterKey": { "type": "string" }
+  },
+  "requires": { "bins": ["docker"] }
+}
+```
+
+---
+
+## Hooks
+
+The plugin registers three OpenClaw lifecycle hooks:
+
+### before_agent_start
+- Detects sub-agent sessions and provisions email accounts
+- Resolves parent agent email for auto-CC
+- Sends introduction email in coordination thread
+- Injects identity context, security rules, and unread mail summary into system prompt
+
+### before_tool_call
+- Injects sub-agent API keys for `agenticmail_*` tools
+- Pushes pending email notifications from SSE watchers
+- Captures spawn info from `sessions_spawn` (enforces minimum 10-minute timeout)
+
+### agent_end
+- Cancels all pending follow-up reminders
+- Removes agent from registries
+- Stops SSE watcher
+- Delays account deletion by 5 seconds (grace period for in-flight operations)
+- Deletes the sub-agent's Stalwart account
+
+---
+
+## License
+
+[MIT](./LICENSE) - Ope Olatunji ([@ope-olatunji](https://github.com/ope-olatunji))