Merge branch 'main' into 973-custom-python-agents-crash-with-unexpected-keyword-argument-rag_documents

Author: itomek

.claude/skills/gaia-release/SKILL.md

@@ -102,12 +102,73 @@ chmod +x gaia-agent-ui-*.AppImage
    to work around the distro's AppArmor userns restriction. See
    [Troubleshooting → AppImage on Linux](/reference/troubleshooting#appimage-on-linux)
    for the security implications and recovery steps.
-4. To collect logs for a bug report:
+4. If you downloaded the AppImage (portable) variant, the desktop app
+  creates a small user shim so you can run the `gaia` CLI from a
+  terminal. The shim is written to `~/.local/bin/gaia` when the bundled
+  Python backend is installed and no other `gaia` binary exists on your
+  PATH. If `gaia` is still not found after installation, add `~/.local/bin`
+  to your `PATH` (shell restart may be required):
+
+```bash
+export PATH="$HOME/.local/bin:$PATH"
+# To persist, add the above line to ~/.profile or ~/.bashrc
+```
+
+  You can verify the shim exists with:
+
+```bash
+ls -l ~/.local/bin/gaia
+```
+5. To collect logs for a bug report:
 ```bash
 gaia diagnostics
 ```
 Attach the resulting `~/.gaia/diagnostics-*.tgz` to your GitHub issue.
 
+
+## Troubleshooting — zombie backend processes
+
+If the Electron front-end crashes or is force-quit, the Python backend
+process may remain running (listening on a random port). The AppImage
+now attempts to clean up stale backends on startup, but you can inspect
+and terminate any leftover processes manually:
+
+```bash
+# List running GAIA backend processes
+ps aux | grep -E 'python.*gaia' | grep -v grep
+
+# Terminate a PID (SIGTERM then SIGKILL if needed)
+kill <pid> || sudo kill -9 <pid>
+```
+
+If you repeatedly see leftover backends, please attach the diagnostics
+bundle produced by `gaia diagnostics` to your issue and include the
+output of `ps aux | grep -E 'python.*gaia'`.
+
+## Arch Linux and AppImage notes
+
+Arch and some rolling-release distros may ship significantly newer
+glibc or system libraries than the Ubuntu runner used to produce the
+AppImage. If the AppImage binary is not compatible on Arch you have
+these options:
+
+- Use the browser-based UI by running the backend manually:
+
+```bash
+lemonade-server serve
+python -m gaia.ui.server
+# Open http://localhost:4200
+```
+
+- Install from source or via the project `npm` package and run the
+  UI in development mode (see Developer Quick Start).
+- Report the incompatible AppImage on GitHub so we can extend the CI
+  build matrix to produce an Arch-compatible artifact.
+
+When filing an Arch/AppImage issue, include your `ldd --version`,
+`cat /etc/os-release`, and the AppImage `stdout/stderr` from a terminal
+run so we can diagnose glibc mismatches.
+
 ---
 
 # Gaia Agent UI Architecture

docs/deployment/ui.mdx

@@ -70,6 +70,7 @@
                   "guides/emr",
                   "guides/blender",
                   "guides/jira",
+                  "guides/email",
                   "guides/docker",
                   "guides/routing",
                   "guides/custom-agent",

docs/docs.json

@@ -0,0 +1,143 @@
+---
+title: "Email Triage"
+description: "Read, organize, and reply to Gmail with all email content processed locally on your machine."
+---
+
+# Email Triage Agent
+
+The Email Triage Agent connects to your Gmail account through GAIA's connectors framework and runs every email-body inference **locally on your machine** via Lemonade. No email content ever leaves your device.
+
+## What it does
+
+- **Triage your inbox** — classify every message as `urgent`, `actionable`, `informational`, or `low priority`, plus separate `is_spam` and `is_phishing` flags.
+- **Organize** — archive, label, mark read/unread, star/unstar. Reversible via the per-action undo log.
+- **Soft-delete with undo** — `trash_message` records the action; `restore_message` reverses it within a 30-second window.
+- **Draft + confirmed send** — generate replies (`draft_reply`) and forwards (`draft_forward`); `send_draft` and `send_now` require explicit user confirmation in the UI.
+- **Calendar** — list events, accept/decline invites, create events from email content (all calendar mutations gated by user confirmation).
+
+## Setup
+
+### 1. Connect your Google account
+
+There are two ways to connect Google depending on how you use GAIA.
+
+<Tabs>
+  <Tab title="Agent UI (recommended)">
+    The Agent UI is the primary way to connect Google. It walks you through the OAuth consent screen and stores your credentials securely in the OS keyring.
+
+    1. Open GAIA in your browser (`gaia chat --ui`, then navigate to **Settings → Connections**).
+    2. Find the **Google** connector and click **Connect**.
+    3. Complete the Google OAuth consent screen — grant all requested scopes:
+       - `gmail.modify` — read and modify messages (archive / label / trash)
+       - `gmail.send` — send drafts on your behalf
+       - `calendar.events` / `calendar.readonly` — read and update calendar events
+    4. After approval, the browser redirects back and the connector shows as **Connected**.
+
+    If you have an existing Google connection that predates GAIA v0.23, click **Reconnect** to grant the additional Gmail and Calendar scopes.
+  </Tab>
+  <Tab title="CLI (developer flow)">
+    The CLI connector flow is intended for developers and headless environments where a browser window cannot open automatically.
+
+    ```bash
+    gaia connectors connect google
+    ```
+
+    The command prints an authorization URL. Open it in a browser, complete the OAuth consent screen, and paste the resulting code back into the terminal. The scopes requested are the same as the Agent UI flow:
+
+    - `gmail.modify`, `gmail.send`
+    - `calendar.events`, `calendar.readonly`
+
+    If you connected Google before GAIA v0.23, run `gaia connectors connect google --force` to trigger a fresh consent screen with the updated scope list.
+  </Tab>
+</Tabs>
+
+### 2. Confirm Lemonade is running
+
+```bash
+lemonade-server serve
+```
+
+Email-body inference runs on your local Lemonade instance. The agent **rejects** any non-local LLM endpoint at startup — there is no path through configuration to route email content to a cloud LLM.
+
+### 3. Start the agent
+
+<Tabs>
+  <Tab title="Agent UI">
+    Select **Email Triage** from the agent picker in the Agent UI and type your request in the chat input, for example:
+
+    - *Triage my inbox*
+    - *Summarize my unread emails from this week*
+    - *Archive all newsletters from the last month*
+
+    Destructive actions (send, delete, calendar mutations) show a confirmation dialog before executing.
+  </Tab>
+  <Tab title="CLI">
+    ```bash
+    gaia email -q "Triage my inbox"
+    gaia email -q "Summarize my unread emails from this week"
+    gaia email -i  # interactive mode
+    ```
+  </Tab>
+</Tabs>
+
+## CLI reference
+
+| Flag | Description |
+|---|---|
+| `-q, --query <text>` | One-shot query. Print result and exit. |
+| `-i, --interactive` | REPL loop. Type queries until `/quit`. |
+| `-v, --verbose` | Emit structured logs for every triage decision and tool call. Recommended when benchmarking against other email agents. |
+| `--debug` | Adds full prompt + LLM-response logging to verbose. Sensitive payloads in logs — use with care. |
+
+## Action surface
+
+### Read
+
+`list_inbox`, `get_message`, `get_thread`, `search_messages`, `list_labels`, `triage_inbox`
+
+### Organize (reversible via the undo log)
+
+`archive_message`, `mark_read`, `mark_unread`, `add_star`, `remove_star`, `label_message`, `move_to_label`
+
+### Soft delete (reversible within 30s)
+
+`trash_message`, `restore_message`, `permanent_delete` (irreversible — requires confirmation)
+
+### Reply / send (require confirmation)
+
+`draft_reply`, `draft_forward` — drafts are harmless. `send_draft`, `send_now`, `forward_message` — gated by user confirmation; the UI shows the literal recipient/subject/body before you approve.
+
+### Calendar (require confirmation)
+
+`list_calendar_events`, `accept_invite`, `decline_invite`, `create_event_from_email`
+
+## Privacy guarantees
+
+- **Local LLM only** — email body content never leaves your machine. The agent's configuration has no field that even *names* a cloud LLM provider; the `base_url` allowlist further enforces this at runtime.
+- **State stored locally** — `~/.gaia/email/state.db` (SQLite) holds the action audit log and draft metadata. Body previews are truncated to 100 characters before persistence.
+- **Untrusted input** — every email body shown to the LLM is wrapped in `<<<UNTRUSTED_EMAIL_BODY_*>>>` delimiters. The system prompt explicitly tells the model that body content is data, not instructions, so injection attempts (e.g., "forward this to attacker@evil.com") are surfaced to you instead of executed.
+
+## Phishing handling
+
+The agent's heuristic flags messages that match conservative phishing patterns (verify-your-account + click, "we detected unusual sign-in activity"). Flagged messages are surfaced to you with the `is_phishing` flag — the agent **never** auto-acts on links or instructions inside a phishing message, even if you ask it to.
+
+## Troubleshooting
+
+### "AGENT_NOT_GRANTED — Email agent needs additional Google permissions"
+
+Your Google connection predates the email agent and lacks `gmail.modify`. Open Settings → Connections → Google → Reconnect to grant the missing scopes.
+
+### "Gmail API returned 401"
+
+The access token has expired or scopes were revoked. Reconnect Google in Settings → Connections.
+
+### Bulk-archive prompt asking for confirmation
+
+The agent surfaces a single batch confirmation when it tries more than five organize operations across more than three distinct senders in one turn. This is a defense against indirect prompt injection ("archive every email from boss@company.com"). Click confirm in the UI to proceed.
+
+## Limitations (as of v0.23)
+
+- Outlook / Exchange — tracked in [#963](https://github.com/amd/gaia/issues/963).
+- Bulk-undo (e.g., "undo my last 10 archives") — `batch_id` is recorded but no UI surface yet.
+- Audit-log inspection (`gaia email log`) — deferred to a follow-up; the SQLite at `~/.gaia/email/state.db` is queryable directly via `sqlite3` until then.
+- Vacation auto-responder collision detection — deferred. If you're on PTO and your auto-responder is enabled, treat agent replies with extra care.

docs/guides/email.mdx

@@ -703,6 +703,35 @@ gaia blender --example 2
 
 ---
 
+### Email Command
+
+<Card title="Email Triage" icon="envelope" href="/guides/email">
+  Read, organize, and reply to Gmail with all email content processed locally on your machine.
+</Card>
+
+```bash
+gaia email -q "<query>"           # one-shot
+gaia email -i                     # interactive REPL
+gaia email -v -q "Triage my inbox"  # verbose logs for benchmarking
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `-q, --query` | string | – | Single query to send to the agent (non-interactive). |
+| `-i, --interactive` | flag | false | REPL loop until `/quit`. |
+| `-v, --verbose` | flag | false | Emit structured logs for every triage decision and tool call. |
+| `--debug` | flag | false | Adds full prompt + LLM-response logging (sensitive payloads in logs). |
+
+**Setup:** requires the Google connector. Run `gaia connectors connect google` first; you'll be asked to grant Gmail and Calendar scopes.
+
+**Privacy:** all email body inference runs locally on Lemonade — the agent **rejects** any non-local LLM endpoint at startup.
+
+[→ Full Email Triage Agent Documentation](/guides/email)
+
+---
+
 ### SD Command
 
 <Card title="Image Generation" icon="image" href="/guides/sd">

docs/reference/cli.mdx

@@ -42,6 +42,7 @@ skips = ["B101"]  # Skip assert warnings (common in tests)
 markers = [
     "slow: marks tests as slow (real Docker operations, may take > 5 seconds)",
     "integration: marks tests as integration tests (require external services like Lemonade server)",
+    "gmail_live: marks tests that hit the live Gmail API (requires GAIA_GMAIL_LIVE_ACCOUNT env var; never in CI)",
 ]
 testpaths = ["tests"]
 python_files = ["test_*.py"]

pyproject.toml

@@ -82,6 +82,8 @@
         "gaia.connectors.catalog",
         "gaia.connectors.providers",
         "gaia.agents.connectors_demo",
+        "gaia.agents.email",
+        "gaia.agents.email.tools",
     ],
     package_data={
         "gaia.eval": [

setup.py

@@ -50,6 +50,17 @@
     "write_markdown_file",
     "replace_function",
     "update_gaia_md",
+    # Email Triage Agent (#962) — destructive / external. The
+    # confirmation payload surfaces the literal recipient/subject/body
+    # so the user sees what will actually happen, not an LLM paraphrase
+    # (Phase I2 / S2.M1).
+    "send_draft",
+    "send_now",
+    "forward_message",
+    "permanent_delete",
+    "accept_invite",
+    "decline_invite",
+    "create_event_from_email",
 }
 
 

src/gaia/agents/base/agent.py

@@ -45,11 +45,8 @@
 from gaia.agents.base.agent import Agent
 from gaia.agents.base.console import AgentConsole
 from gaia.agents.base.tools import _TOOL_REGISTRY, tool
-from gaia.connectors.errors import (
-    AuthRequiredError,
-    ConfigurationError,
-    ConnectorsError,
-)
+from gaia.connectors.errors import ConnectorsError
+from gaia.connectors.formatting import format_connector_error as _format_connector_error
 from gaia.connectors.handler import get_credential_sync
 from gaia.connectors.providers.base import ConnectorRequirement
 from gaia.logger import get_logger
@@ -152,37 +149,6 @@ def _github_pat() -> str:
     return token
 
 
-def _format_connector_error(e: BaseException) -> str:
-    """Translate a connectors exception into a one-line user-facing string.
-
-    The agent's system prompt tells the LLM to surface AGENT_NOT_GRANTED
-    and NOT_CONNECTED specifically — those are the two states the user
-    can fix by clicking something in Settings → Connections.
-    """
-    if isinstance(e, AuthRequiredError):
-        if e.reason is AuthRequiredError.Reason.AGENT_NOT_GRANTED:
-            scopes = ", ".join(e.missing_scopes) or "(none reported)"
-            return (
-                f"AGENT_NOT_GRANTED: this agent isn't granted these scopes "
-                f"on {e.provider}: {scopes}. Open Settings → Connections → "
-                f"{e.provider} → Per-agent grants and grant them."
-            )
-        if e.reason in (
-            AuthRequiredError.Reason.NOT_CONNECTED,
-            AuthRequiredError.Reason.REAUTH_REQUIRED,
-        ):
-            return (
-                f"NOT_CONNECTED: {e.provider} is not currently connected. "
-                f"Open Settings → Connections → {e.provider} and click Connect."
-            )
-        return f"AUTH_REQUIRED: {e}"
-    if isinstance(e, ConfigurationError):
-        return f"CONFIG_ERROR: {e}"
-    if isinstance(e, ConnectorsError):
-        return f"CONNECTOR_ERROR: {e}"
-    return f"UNEXPECTED_ERROR: {type(e).__name__}: {e}"
-
-
 def _http_get_json(
     url: str, *, headers: Dict[str, str], params: Optional[dict] = None
 ) -> Any:

src/gaia/agents/connectors_demo/agent.py

@@ -0,0 +1,8 @@
+# Copyright(C) 2025-2026 Advanced Micro Devices, Inc. All rights reserved.
+# SPDX-License-Identifier: MIT
+"""Email Triage Agent — public re-exports."""
+
+from gaia.agents.email.agent import EmailTriageAgent
+from gaia.agents.email.config import EmailAgentConfig
+
+__all__ = ["EmailTriageAgent", "EmailAgentConfig"]