Skip to content

Agent Zero AI framework

Improve Email plugin settings experience

Alessandroccb63de56404
diff --git a/plugins/_email_integration/AGENTS.md b/plugins/_email_integration/AGENTS.md
index 42c905244..a55c74fd3 100644
--- a/plugins/_email_integration/AGENTS.md
+++ b/plugins/_email_integration/AGENTS.md
@@ -9,7 +9,7 @@
- `helpers/handler.py` owns mailbox polling, state, dispatch, routing, and reply flow.
- `helpers/imap_client.py` and `helpers/smtp_client.py` own inbound and outbound mail transports.
- `helpers/dispatcher.py`, `prompts/`, and attachment helpers own routing decisions and message formatting.
-- `api/`, `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own tests, settings, metadata, hooks, and config UI.
+- `api/`, `default_config.yaml`, `plugin.yaml`, `extensions/`, and `webui/` own tests, scoped settings, metadata, hooks, configuration, and the secret-free status dashboard.
## Local Contracts
@@ -17,6 +17,8 @@
- IMAP accepts exactly one valid From mailbox, rejecting duplicate fields, groups, and parser defects before body processing. Match the whitelist and address replies using that mailbox's normalized address; From filtering does not authenticate sender identity.
- Preserve UID/state tracking so restarts do not duplicate old mail.
- Keep SMTP replies threaded and safe around user-visible errors.
+- Keep the Open page and status API free of passwords and server credentials.
+- Preserve native project and agent-profile configuration scope support.
## Work Guidance
@@ -25,7 +27,7 @@
## Verification
- Smoke-test connection checks, polling, attachment handling, dispatch routing, and SMTP replies when practical.
-- Run `PYTHONPATH=. pytest -q tests/test_email_integration_sender.py` for inbound sender validation and SMTP recipient regression coverage.
+- Run `PYTHONPATH=. pytest -q tests/test_email_plugin_ui.py tests/test_email_integration_sender.py` for UI contracts, secret-free status, inbound sender validation, and SMTP recipient regression coverage.
## Child DOX Index
diff --git a/plugins/_email_integration/api/status.py b/plugins/_email_integration/api/status.py
new file mode 100644
index 000000000..691726a55
--- /dev/null
+++ b/plugins/_email_integration/api/status.py
@@ -0,0 +1,47 @@
+"""Return secret-free status for configured email inboxes."""
+
+import sys
+
+from helpers import plugins
+from helpers.api import ApiHandler, Request
+
+
+PLUGIN_NAME = "_email_integration"
+HANDLER_MODULE = "plugins._email_integration.helpers.handler"
+
+
+class Status(ApiHandler):
+
+ async def process(self, input: dict, request: Request) -> dict:
+ config = plugins.get_plugin_config(PLUGIN_NAME) or {}
+ handlers = config.get("handlers", [])
+ module = sys.modules.get(HANDLER_MODULE)
+ tasks = getattr(module, "_poll_tasks", {}) if module else {}
+
+ inboxes = []
+ for index, handler in enumerate(handlers):
+ if not isinstance(handler, dict):
+ continue
+ name = str(handler.get("name") or f"Inbox {index + 1}")
+ task = tasks.get(name)
+ inboxes.append({
+ "name": name,
+ "address": str(handler.get("username") or ""),
+ "enabled": bool(handler.get("enabled")),
+ "configured": bool(
+ handler.get("username")
+ and handler.get("password")
+ and handler.get("imap_server")
+ and (handler.get("smtp_server") or handler.get("imap_server"))
+ ),
+ "running": bool(task and not task.done()),
+ "protocol": "Exchange" if handler.get("account_type") == "exchange" else "IMAP",
+ "project": str(handler.get("project") or "Default project"),
+ })
+
+ return {
+ "inboxes": inboxes,
+ "total": len(inboxes),
+ "enabled": sum(inbox["enabled"] for inbox in inboxes),
+ "running": sum(inbox["running"] for inbox in inboxes),
+ }
diff --git a/plugins/_email_integration/plugin.yaml b/plugins/_email_integration/plugin.yaml
index 642647e4d..0213e027c 100644
--- a/plugins/_email_integration/plugin.yaml
+++ b/plugins/_email_integration/plugin.yaml
@@ -4,5 +4,5 @@ description: Communicate with Agent Zero via email. Supports IMAP/Exchange inbox
version: 1.0.0
settings_sections:
- external
-per_project_config: false
-per_agent_config: false
+per_project_config: true
+per_agent_config: true
diff --git a/plugins/_email_integration/webui/config.html b/plugins/_email_integration/webui/config.html
index 014de89c1..6628f374a 100644
--- a/plugins/_email_integration/webui/config.html
+++ b/plugins/_email_integration/webui/config.html
@@ -286,13 +286,17 @@
</template>
</div>
- <details class="email-advanced" x-show="$store.emailConfig.hasProvider(handler)">
- <summary>
+ <div class="settings-advanced-section" x-data="{ advOpen: false }"
+ x-show="$store.emailConfig.hasProvider(handler)">
+ <button type="button" class="settings-advanced-toggle"
+ :aria-expanded="advOpen" @click="advOpen = !advOpen">
+ <x-icon class="settings-advanced-toggle-icon"
+ :style="advOpen ? 'transform:rotate(90deg)' : ''"
+ name="chevron_right"></x-icon>
<span>Advanced</span>
- <x-icon class="email-advanced-chevron"
- aria-hidden="true" name="keyboard_arrow_down"></x-icon>
- </summary>
- <div class="email-advanced-body">
+ </button>
+ <div class="settings-advanced-body" x-show="advOpen" x-transition.opacity
+ style="display: none;">
<div class="field">
<div class="field-label">
<div class="field-title">Inbox name</div>
@@ -486,7 +490,7 @@
</div>
</div>
- </details>
+ </div>
</div>
</template>
</div>
@@ -508,35 +512,6 @@
gap: 0.9rem;
}
- .email-advanced summary {
- cursor: pointer;
- list-style: none;
- font-weight: 700;
- display: flex;
- align-items: center;
- gap: 0.75rem;
- }
-
- .email-advanced summary::-webkit-details-marker {
- display: none;
- }
-
- .email-advanced summary {
- padding: 0.95rem 1rem;
- }
-
- .email-advanced-chevron {
- margin-left: auto;
- flex: 0 0 auto;
- transition: transform 0.18s ease, opacity 0.18s ease;
- opacity: 0.72;
- }
-
- .email-advanced[open] .email-advanced-chevron {
- transform: rotate(180deg);
- opacity: 1;
- }
-
.email-guide-card {
border: 1px solid color-mix(in srgb, var(--color-border) 80%, white 20%);
border-radius: 12px;
diff --git a/plugins/_email_integration/webui/email-main-store.js b/plugins/_email_integration/webui/email-main-store.js
new file mode 100644
index 000000000..6a25870e8
--- /dev/null
+++ b/plugins/_email_integration/webui/email-main-store.js
@@ -0,0 +1,31 @@
+import { createStore } from "/js/AlpineStore.js";
+import { callJsonApi } from "/js/api.js";
+import { toastFrontendError } from "/components/notifications/notification-store.js";
+
+const PLUGIN_NAME = "_email_integration";
+
+export const store = {
+ loading: true,
+ status: { inboxes: [], total: 0, enabled: 0, running: 0 },
+
+ async init() {
+ await this.refresh();
+ },
+
+ async refresh() {
+ this.loading = true;
+ try {
+ this.status = await callJsonApi(`/plugins/${PLUGIN_NAME}/api/status`, {});
+ } catch (error) {
+ toastFrontendError(error, "Could not load email status");
+ } finally {
+ this.loading = false;
+ }
+ },
+
+ openConfig() {
+ window.Alpine.store("pluginSettings").openConfig(PLUGIN_NAME);
+ },
+};
+
+createStore("emailMain", store);
diff --git a/plugins/_email_integration/webui/main.html b/plugins/_email_integration/webui/main.html
new file mode 100644
index 000000000..1246c88f7
--- /dev/null
+++ b/plugins/_email_integration/webui/main.html
@@ -0,0 +1,218 @@
+<html>
+
+<head>
+ <title>Email Integration</title>
+ <script type="module">
+ import { store } from "/plugins/_email_integration/webui/email-main-store.js";
+ </script>
+</head>
+
+<body>
+ <main class="email-main" x-data x-init="$store.emailMain.init()">
+ <header class="email-main-header">
+ <div>
+ <div class="section-title">Email Integration</div>
+ <p>Monitor the inboxes that connect email conversations to Agent Zero.</p>
+ </div>
+ <div class="email-main-actions">
+ <button type="button" class="btn btn-field" @click="$store.emailMain.refresh()"
+ :disabled="$store.emailMain.loading">
+ <x-icon name="refresh"></x-icon>
+ Refresh
+ </button>
+ <button type="button" class="btn btn-field" @click="$store.emailMain.openConfig()">
+ <x-icon name="settings"></x-icon>
+ Configure
+ </button>
+ </div>
+ </header>
+
+ <template x-if="$store.emailMain.loading">
+ <div class="email-main-empty">Loading inbox status...</div>
+ </template>
+
+ <template x-if="!$store.emailMain.loading">
+ <div>
+ <section class="email-main-summary" aria-label="Email integration summary">
+ <div><strong x-text="$store.emailMain.status.total"></strong><span>Connected inboxes</span></div>
+ <div><strong x-text="$store.emailMain.status.enabled"></strong><span>Enabled</span></div>
+ <div><strong x-text="$store.emailMain.status.running"></strong><span>Polling now</span></div>
+ </section>
+
+ <template x-if="$store.emailMain.status.inboxes.length === 0">
+ <section class="email-main-empty">
+ <x-icon name="mail"></x-icon>
+ <strong>No inboxes connected</strong>
+ <span>Open configuration to connect the first email account.</span>
+ <button type="button" class="btn btn-field" @click="$store.emailMain.openConfig()">Connect inbox</button>
+ </section>
+ </template>
+
+ <section class="email-main-list" x-show="$store.emailMain.status.inboxes.length > 0">
+ <template x-for="inbox in $store.emailMain.status.inboxes" :key="inbox.name">
+ <article class="email-main-row">
+ <div class="email-main-icon"><x-icon name="alternate_email"></x-icon></div>
+ <div class="email-main-copy">
+ <strong x-text="inbox.name"></strong>
+ <span x-text="inbox.address || 'Email address not set'"></span>
+ </div>
+ <div class="email-main-meta">
+ <span x-text="inbox.protocol"></span>
+ <span x-text="inbox.project"></span>
+ </div>
+ <span class="email-main-state"
+ x-text="inbox.running ? 'Polling' : (inbox.enabled ? (inbox.configured ? 'Starting' : 'Needs setup') : 'Off')"></span>
+ </article>
+ </template>
+ </section>
+ </div>
+ </template>
+ </main>
+
+ <style>
+ .email-main {
+ display: flex;
+ flex-direction: column;
+ gap: var(--spacing-md);
+ color: var(--color-text);
+ font-family: var(--font-family-main);
+ }
+
+ .email-main-header,
+ .email-main-actions,
+ .email-main-row,
+ .email-main-meta {
+ display: flex;
+ align-items: center;
+ }
+
+ .email-main-header {
+ justify-content: space-between;
+ gap: var(--spacing-md);
+ }
+
+ .email-main-header p {
+ margin: 0.3rem 0 0;
+ color: var(--color-text-secondary);
+ }
+
+ .email-main-actions,
+ .email-main-meta {
+ gap: var(--spacing-sm);
+ }
+
+ .email-main-summary {
+ display: grid;
+ grid-template-columns: repeat(3, minmax(0, 1fr));
+ border-block: 1px solid var(--color-border);
+ }
+
+ .email-main-summary div {
+ display: flex;
+ flex-direction: column;
+ gap: 0.25rem;
+ padding: var(--spacing-md);
+ }
+
+ .email-main-summary div + div {
+ border-left: 1px solid var(--color-border);
+ }
+
+ .email-main-summary strong {
+ font-size: 1.6rem;
+ }
+
+ .email-main-summary span,
+ .email-main-copy span,
+ .email-main-meta,
+ .email-main-empty span {
+ color: var(--color-text-secondary);
+ font-size: var(--font-size-small);
+ }
+
+ .email-main-list {
+ margin-top: var(--spacing-md);
+ }
+
+ .email-main-row {
+ gap: var(--spacing-md);
+ padding: var(--spacing-md) 0;
+ border-bottom: 1px solid var(--color-border);
+ }
+
+ .email-main-icon {
+ display: grid;
+ place-items: center;
+ width: 2.5rem;
+ height: 2.5rem;
+ border: 1px solid var(--color-border);
+ border-radius: 50%;
+ }
+
+ .email-main-copy {
+ display: flex;
+ flex: 1;
+ flex-direction: column;
+ gap: 0.2rem;
+ min-width: 0;
+ }
+
+ .email-main-copy span {
+ overflow: hidden;
+ text-overflow: ellipsis;
+ white-space: nowrap;
+ }
+
+ .email-main-meta {
+ flex-wrap: wrap;
+ }
+
+ .email-main-meta span,
+ .email-main-state {
+ padding: 0.25rem 0.55rem;
+ border: 1px solid var(--color-border);
+ border-radius: 999px;
+ font-size: var(--font-size-small);
+ }
+
+ .email-main-state {
+ min-width: 5.5rem;
+ text-align: center;
+ }
+
+ .email-main-empty {
+ display: flex;
+ flex-direction: column;
+ align-items: center;
+ gap: var(--spacing-sm);
+ padding: calc(var(--spacing-lg) * 2) var(--spacing-md);
+ text-align: center;
+ }
+
+ @media (max-width: 680px) {
+ .email-main-header,
+ .email-main-row {
+ align-items: stretch;
+ flex-direction: column;
+ }
+
+ .email-main-actions .btn {
+ flex: 1;
+ }
+
+ .email-main-summary div {
+ padding: var(--spacing-sm);
+ }
+
+ .email-main-meta {
+ justify-content: flex-start;
+ }
+
+ .email-main-state {
+ align-self: flex-start;
+ }
+ }
+ </style>
+</body>
+
+</html>
diff --git a/tests/test_email_plugin_ui.py b/tests/test_email_plugin_ui.py
new file mode 100644
index 000000000..0f38da16a
--- /dev/null
+++ b/tests/test_email_plugin_ui.py
@@ -0,0 +1,45 @@
+import asyncio
+from pathlib import Path
+
+import yaml
+
+from plugins._email_integration.api.status import Status
+
+
+ROOT = Path(__file__).resolve().parents[1]
+PLUGIN = ROOT / "plugins" / "_email_integration"
+
+
+def test_email_plugin_exposes_scoped_config_and_shared_webui():
+ metadata = yaml.safe_load((PLUGIN / "plugin.yaml").read_text())
+ config_html = (PLUGIN / "webui" / "config.html").read_text()
+ main_html = (PLUGIN / "webui" / "main.html").read_text()
+
+ assert metadata["per_project_config"] is True
+ assert metadata["per_agent_config"] is True
+ assert "settings-advanced-section" in config_html
+ assert 'class="email-advanced"' not in config_html
+ assert "var(--color-" in main_html
+
+
+def test_email_status_omits_credentials(monkeypatch):
+ config = {
+ "handlers": [{
+ "name": "Support",
+ "enabled": True,
+ "account_type": "imap",
+ "username": "[email protected]",
+ "password": "super-secret",
+ "imap_server": "imap.example.com",
+ "smtp_server": "smtp.example.com",
+ }]
+ }
+ monkeypatch.setattr(
+ "plugins._email_integration.api.status.plugins.get_plugin_config",
+ lambda name: config,
+ )
+
+ result = asyncio.run(Status().process({}, None))
+
+ assert result["inboxes"][0]["configured"] is True
+ assert "super-secret" not in repr(result)