feat(email): quality + robustness batch (#2110/#2113/#2114/#2115/#2116) (#2192)

## Why this matters

Five E2E findings on the Email Triage agent, batched because they share
the same package and (for the LLM-affecting ones) a serial eval.
Per-issue user-observable impact:

- **#2116** — Before: a fresh Google Cloud project without the
Gmail/Calendar API enabled dumped Google's raw 403 JSON into the tool
result. After: GAIA's three-part actionable error naming the enable URL
Google returns in `extendedHelp` + the 1-2 minute propagation note
(shared `google_errors` helper, both backends).
- **#2114** — Before: "archive the Netflix promo" searched the literal
phrase → zero hits → "couldn't find it" even though the message was
present. After: docstring + prompt steer toward `from:`/`subject:`
operators, and a bare-phrase zero-result query retries once as an
operator query. `triage_inbox` gets timeout headroom (600s) over the
180s default for full-inbox scans on slow hardware. _(Maintainer
re-verified the phishing-timeout half no longer reproduces on main;
narrowed to the search-operator half per that comment.)_
- **#2115** — Before: final answers could be a bare render fence with no
prose (CLI/integrators saw empty replies) and carried LaTeX artifacts
(`$\rightarrow$`); the settings-path label drifted between
"Connectors"/"Connections". After: prompt requires prose alongside any
render payload and forbids TeX; LaTeX normalized at the output boundary;
every settings-path string says "Connectors" (Outlook backends +
connectors-demo + webui comment) with a grep-level consistency guard.
- **#2113** — Before: a Gmail promotions/social/updates label
short-circuited the heuristic to a confident classification before any
body read, so a real deadline / attendance requirement / "budget
exceeded" consequence was confidently archived or filed informational.
After: a body-signal veto forces LLM escalation when a
deadline/commitment/consequence signal is present; ordinary marketing
urgency ("sale ends", "limited time") still archives confidently. Adds
synthetic commitment cases to the eval corpus seed.
- **#2110** — Before: "daily briefing" and "extract action items" had no
agent-loop tool and silently degraded to a raw `pre_scan_inbox` fence
(dishonest by omission). After: `get_briefing`, `list_tasks`, and
`extract_action_items` are registered agent-loop tools; the prompt binds
each NL ask to its dedicated tool. `extract_action_items` drives a fresh
scan so a cold "what do I need to do?" works. Capability matrix +
`tools_count` (52→55) + guide synced.

## Status — ready for review

All five issues are implemented, rebased on current `main`, and the full
deterministic CI is green (unit + integration email suites,
connectors-demo, code-quality/lint). No stubs or half-finished paths.

**Verified in CI:**
- #2113 veto mechanism: promotions/social/updates + commitment signal →
`confident=False` escalation; ordinary promos unchanged; corpus cases
present with needs-attention ground truth.
- #2110 tool registration + behavior: all three tools register;
`get_briefing` cold-generates and returns persisted;
`extract_action_items` drives a scan and populates the task store from
cold; `list_tasks` reads back; drift guards (capability matrix,
`tools_count` across 3 sources, and the `test_email_agent` tool-registry
allowlist) green.
- #2114 operator-retry logic + #2116 403 mapping + #2115 LaTeX/naming:
fully unit-tested.

**LLM behavioral eval — self-hosted lane, not a PR gate:** the email
triage benchmark / scorecard (`Email Agent Eval` workflow) runs on the
self-hosted Windows/strix-halo Lemonade pool via weekly cron +
`workflow_dispatch`; it is not part of PR-gating CI. Its committed
baselines are AMD-hardware-calibrated, so it must be refreshed on that
pool — running it on non-AMD dev hardware would produce non-comparable
numbers. Recommended before/after merge:
- [ ] `workflow_dispatch` the `Email Agent Eval` workflow on the
strix-halo pool; confirm #2113 commitment cases hit the recall bar
without regressing urgent/needs-response, and regenerate the AMD
baselines if the batch shifts them.

## Test plan

- [x] Rebased on current `origin/main` (clean merge — no conflicts).
- [x] `python util/lint.py --all` — green.
- [x] Email Agent Unit Tests (py3.10 + py3.12 CI matrix) — green (2603
passed / 6 skipped locally in a clean-install venv).
- [x] Test Email Agent (integration + repo-side email unit suite) —
green after adding the #2110 tools to the `test_email_agent` registry
allowlist.
- [x] Test Connectors Demo Agent — green (naming change).

Part of #2014
Closes #2116
Closes #2114
Closes #2115
Closes #2113
Closes #2110

---------

Co-authored-by: Ovtcharov <kovtchar@amd.com>
Co-authored-by: Kalin Ovtcharov <kalin@extropolis.ai>

Author: 3 people

docs/guides/email.mdx

@@ -233,6 +233,14 @@ are planned on the autonomy engine (#555).
 
 `list_inbox`, `get_message`, `get_thread`, `search_messages`, `list_labels`, `triage_inbox`, `pre_scan_inbox`, `check_followups`
 
+### Briefing & tasks
+
+`get_briefing`, `list_tasks`, `extract_action_items` — natural-language asks like
+"give me a daily briefing", "what do I need to do from my inbox", and "show my
+tasks" bind to these dedicated tools. `extract_action_items` drives a fresh scan
+of your recent mail (it does not require a prior triage run), and `get_briefing`
+returns the latest scheduled briefing or generates one on demand.
+
 ### Classification preferences (persist across restarts)
 
 `set_priority_sender`, `set_low_priority_sender`, `set_category_default`, `clear_session_preferences`

hub/agents/python/connectors-demo/gaia_agent_connectors_demo/agent.py

@@ -14,7 +14,7 @@
 2. ``get_credential_sync(connector_id, agent_id, required_scopes)``
    — the central entrypoint that fires the grant-ledger check before
    returning a usable credential.
-3. The Settings → Connections per-agent grants UI — the user must be
+3. The Settings → Connectors per-agent grants UI — the user must be
    able to grant scopes from inside the AgentUI.
 
 This agent ships four tools that fan out across two connector kinds:
@@ -92,9 +92,9 @@
 - Call exactly the tool that matches the question. Don't speculate;
   if the user asks "what's in my inbox?" call gmail_recent_subjects.
 - If a tool returns an error mentioning "AGENT_NOT_GRANTED", tell the
-  user which scope they need to grant in Settings → Connections.
+  user which scope they need to grant in Settings → Connectors.
 - If a tool returns an error mentioning "NOT_CONNECTED", tell them to
-  connect that service in Settings → Connections first.
+  connect that service in Settings → Connectors first.
 - Summarize tool output in 1–3 sentences. Don't recite raw JSON.
 - Do NOT make up data. If a tool fails, say so.
 """
@@ -146,7 +146,7 @@ def _github_pat() -> str:
     if not token:
         raise ConnectorsError(
             "GitHub MCP credential resolved but GITHUB_TOKEN was empty. "
-            "Re-run Settings → Connections → GitHub → Configure to set the "
+            "Re-run Settings → Connectors → GitHub → Configure to set the "
             "Personal Access Token."
         )
     return token

hub/agents/python/email/CAPABILITY_MATRIX.md

@@ -46,7 +46,8 @@ python hub/agents/python/email/packaging/capability_matrix.py
 
 ## Surface totals
 
-- Internal `@tool` agent-loop functions: **52**
+- Internal `@tool` agent-loop functions: **55**
+  - `briefing_tools`: 3
   - `calendar_tools`: 6
   - `delete_tools`: 3
   - `followup_tools`: 1

hub/agents/python/email/gaia-agent.yaml

@@ -19,7 +19,7 @@ icon: mail
 # tests/test_capability_matrix.py (AST-derived, reconciled against
 # __init__.py) and tests/test_email_agent.py (live registry, #1232);
 # a mismatch fails CI.
-tools_count: 52
+tools_count: 55
 
 language: python
 min_gaia_version: "0.22.0"

hub/agents/python/email/gaia_agent_email/__init__.py

@@ -120,5 +120,5 @@ def email_factory(**kwargs):
         category="productivity",
         tags=["email", "gmail", "calendar", "triage"],
         icon="mail",
-        tools_count=52,  # guarded by tests/test_email_agent.py (#1232)
+        tools_count=55,  # guarded by tests/test_email_agent.py (#1232)
     )

hub/agents/python/email/gaia_agent_email/agent.py

@@ -37,7 +37,7 @@ class never passes ``use_claude=True`` / ``use_chatgpt=True`` to
 from pathlib import Path
 from typing import Any, ClassVar, Dict, List, Optional
 
-from gaia_agent_email import action_store, schedule_store
+from gaia_agent_email import action_store, schedule_store, task_store
 from gaia_agent_email.config import ConfigurationError, EmailAgentConfig
 from gaia_agent_email.model_select import (
     NPU_EMAIL_MODEL_ID,
@@ -53,6 +53,7 @@ class never passes ``use_claude=True`` / ``use_chatgpt=True`` to
     ALL_SCOPES,
 )
 from gaia_agent_email.supervision import is_daemon_supervised
+from gaia_agent_email.tools.briefing_tools import BriefingToolsMixin
 from gaia_agent_email.tools.calendar_tools import CalendarToolsMixin
 from gaia_agent_email.tools.delete_tools import DeleteToolsMixin
 from gaia_agent_email.tools.followup_tools import FollowupToolsMixin
@@ -174,10 +175,11 @@ def _detect_targeted_mailboxes(query: str) -> set:
 
 ACTIONS:
 - Read tools (list_inbox, get_message, get_thread, search_messages,
-  list_labels, triage_inbox, pre_scan_inbox, check_followups) — never
-  require confirmation. check_followups flags sent mail still awaiting a
-  reply; it only reports — never draft or send a follow-up nudge unless the
-  user explicitly asks, and any send remains confirmation-gated.
+  list_labels, triage_inbox, pre_scan_inbox, check_followups, get_briefing,
+  list_tasks, extract_action_items) — never require confirmation.
+  check_followups flags sent mail still awaiting a reply; it only reports —
+  never draft or send a follow-up nudge unless the user explicitly asks, and
+  any send remains confirmation-gated.
 - Organize tools (archive_message, mark_read, mark_unread, add_star,
   remove_star, label_message, move_to_label) — reversible via the undo
   log; do not require per-action confirmation, but bulk operations
@@ -220,6 +222,24 @@ def _detect_targeted_mailboxes(query: str) -> set:
 do not re-state its contents in prose. For follow-up questions about
 specific items, refer to the message_id values from the card.
 
+ALWAYS write at least one sentence of plain prose in your final answer. A
+render payload (a ```email_pre_scan fence or any raw JSON) must NEVER stand
+alone as your entire reply — render-less consumers (CLI, integrators) see
+only your text, so a bare fence reads as an empty answer to them. If you
+have nothing to add beyond the card, still write the one framing sentence.
+
+BRIEFING & TASKS:
+- For a daily briefing / morning brief / "summarize my inbox for today",
+  call ``get_briefing`` — NOT ``pre_scan_inbox``. The briefing is the
+  dedicated tool for that ask; do not fall back to a raw pre-scan.
+- For "extract action items" / "what do I need to do from my inbox", call
+  ``extract_action_items`` — it scans your recent mail and captures the
+  to-dos even if you have not triaged yet.
+- For "show my tasks" / "what's on my task list", call ``list_tasks``
+  (add status 'open' or 'done' to filter).
+Never answer any of these three asks with a bare ``pre_scan_inbox`` fence —
+each has its own tool.
+
 MAILBOX TARGETING:
 Read/triage tools scan only CONNECTED mailboxes, and every result item is
 tagged with its source mailbox (google or microsoft). If the user asks
@@ -228,13 +248,74 @@ def _detect_targeted_mailboxes(query: str) -> set:
 NEVER present one mailbox's data as if it came from the provider the user
 asked for.
 
+SEARCH:
+When searching, translate the user's words into Gmail operators — never pass
+the raw phrase to search_messages. "archive the Netflix promo email" →
+search_messages("from:netflix"), NOT search_messages("Netflix promotional
+email"). Map a sender/brand to ``from:``, expected subject words to
+``subject:``, and status/recency to ``is:unread`` / ``newer_than:7d`` /
+``label:promotions``. A literal-phrase search that returns zero results has
+almost certainly mis-formed the query — retry with ``from:``/``subject:``
+operators before telling the user the message can't be found.
+
 OUTPUT:
 Tool results come back as JSON envelopes ``{"ok": true, "data": ...}``
 or ``{"ok": false, "error": "..."}``. Summarize tool output briefly for
-the user — do not recite raw JSON.
+the user — do not recite raw JSON. Write plain text only: use Unicode
+symbols directly (→, ≤, ×), never LaTeX/TeX markup like $\\rightarrow$.
 """
 
 
+# ---------------------------------------------------------------------------
+# Output normalization
+# ---------------------------------------------------------------------------
+
+# LaTeX/TeX commands that models sometimes emit inside plain-text answers
+# (e.g. ``$\rightarrow$`` instead of ``→``). Map them to the Unicode symbol.
+_LATEX_SYMBOLS = {
+    r"\rightarrow": "→",
+    r"\Rightarrow": "⇒",
+    r"\leftarrow": "←",
+    r"\Leftarrow": "⇐",
+    r"\leftrightarrow": "↔",
+    r"\to": "→",
+    r"\times": "×",
+    r"\div": "÷",
+    r"\leq": "≤",
+    r"\geq": "≥",
+    r"\neq": "≠",
+    r"\approx": "≈",
+    r"\pm": "±",
+    r"\cdot": "·",
+    r"\ldots": "…",
+    r"\bullet": "•",
+    r"\deg": "°",
+}
+
+# Match an optional ``$``/``\(`` math wrapper around a single known command,
+# so ``$\rightarrow$`` and a bare ``\rightarrow`` both normalize.
+_LATEX_CMD_RE = re.compile(
+    r"\$?\\(" + "|".join(cmd[1:] for cmd in _LATEX_SYMBOLS) + r")\b\$?"
+)
+
+
+def _normalize_plain_text_answer(text: str) -> str:
+    """Strip LaTeX artifacts from a plain-text answer (#2115).
+
+    Models occasionally emit TeX markup (``$\\rightarrow$``) in prose meant
+    to be plain text. Rewrite the known commands to their Unicode symbol so
+    CLI / integrator consumers see ``→`` rather than raw TeX. Leaves text
+    without any such artifact untouched.
+    """
+    if not text or "\\" not in text:
+        return text
+
+    def _sub(m: "re.Match[str]") -> str:
+        return _LATEX_SYMBOLS["\\" + m.group(1)]
+
+    return _LATEX_CMD_RE.sub(_sub, text)
+
+
 # ---------------------------------------------------------------------------
 # Agent
 # ---------------------------------------------------------------------------
@@ -245,6 +326,7 @@ class EmailTriageAgent(
     MemoryMixin,
     DatabaseMixin,
     ReadToolsMixin,
+    BriefingToolsMixin,
     FollowupToolsMixin,
     OrganizeToolsMixin,
     ReplyToolsMixin,
@@ -403,6 +485,7 @@ def __init__(self, config: Optional[EmailAgentConfig] = None):
         self.init_db(db_path)
         action_store.init_schema(self)
         schedule_store.init_schema(self)
+        task_store.init_schema(self)
 
         # LLM connection. Default to Lemonade — the config's base_url
         # allowlist guarantees the host is local. Resolved BEFORE init_memory()
@@ -654,7 +737,12 @@ def process_query(self, user_input: str, *args, **kwargs):
         guard = self._mailbox_target_guard(user_input)
         if guard is not None:
             return guard
-        return super().process_query(user_input, *args, **kwargs)
+        result = super().process_query(user_input, *args, **kwargs)
+        # Normalize LaTeX artifacts at the output boundary so render-less
+        # consumers never see raw TeX in the final answer (#2115).
+        if isinstance(result, dict) and isinstance(result.get("result"), str):
+            result["result"] = _normalize_plain_text_answer(result["result"])
+        return result
 
     def _mailbox_target_guard(self, user_input: str) -> Optional[Dict[str, Any]]:
         """Reject a request that explicitly targets an unavailable mailbox (#2164).
@@ -715,6 +803,7 @@ def _register_tools(self) -> None:
         _TOOL_REGISTRY.clear()
         self._reset_organize_counter()
         self._register_read_tools()
+        self._register_briefing_tools()
         self._register_followup_tools()
         self._register_organize_tools()
         self._register_reply_tools()

hub/agents/python/email/gaia_agent_email/api_routes.py

@@ -412,6 +412,53 @@ def _split_sentences(text: str) -> List[str]:
     return [s.strip() for s in _SENTENCE_SPLIT_RE.split(text) if s.strip()]
 
 
+def extract_action_items_from_body(body: str) -> List[ActionItem]:
+    """Extract action items from a message body (cue-based, deterministic).
+
+    Module-level so both the REST triage path
+    (``EmailTriageService._extract_action_items``) and the agent-loop
+    ``extract_action_items`` tool (#2110) share ONE extractor — the two
+    surfaces can't drift.
+    """
+    items: List[ActionItem] = []
+    seen: set[str] = set()
+    for sentence in _split_sentences(body):
+        low = sentence.lower()
+        if not any(cue in low for cue in _ACTION_CUES):
+            continue
+        normalized = sentence.strip()
+        key = normalized.lower()
+        if key in seen:
+            continue
+        seen.add(key)
+        due_match = _DUE_HINT_RE.search(sentence)
+        due_hint = due_match.group(1) if due_match else None
+        url_match = _URL_RE.search(sentence)
+        if url_match:
+            # Trim trailing sentence punctuation the greedy match grabs
+            # ("...report." → "...report") so the link is well-formed.
+            # Strip char-by-char, but keep a ")" that closes a "(" inside
+            # the URL itself (e.g. .../Python_(programming_language)) so we
+            # don't silently truncate Wikipedia/Confluence-style links.
+            url = url_match.group(0)
+            _trailing = ".,;:!?)]}\"'"
+            while url and url[-1] in _trailing:
+                if url[-1] == ")" and "(" in url:
+                    break
+                url = url[:-1]
+            items.append(
+                ActionItem(
+                    description=normalized,
+                    due_hint=due_hint,
+                    type="link",
+                    url=url,
+                )
+            )
+        else:
+            items.append(ActionItem(description=normalized, due_hint=due_hint))
+    return items
+
+
 def _aggregate_usage(call_stats: List[dict]) -> Optional[TriageUsage]:
     """Sum the per-call usage/stats entries across the classify + summarize
     LLM calls into a single :class:`TriageUsage`.
@@ -901,43 +948,7 @@ def _summarize(self, subject: str, body: str) -> str:
         return summary
 
     def _extract_action_items(self, body: str) -> List[ActionItem]:
-        items: List[ActionItem] = []
-        seen: set[str] = set()
-        for sentence in _split_sentences(body):
-            low = sentence.lower()
-            if not any(cue in low for cue in _ACTION_CUES):
-                continue
-            normalized = sentence.strip()
-            key = normalized.lower()
-            if key in seen:
-                continue
-            seen.add(key)
-            due_match = _DUE_HINT_RE.search(sentence)
-            due_hint = due_match.group(1) if due_match else None
-            url_match = _URL_RE.search(sentence)
-            if url_match:
-                # Trim trailing sentence punctuation the greedy match grabs
-                # ("...report." → "...report") so the link is well-formed.
-                # Strip char-by-char, but keep a ")" that closes a "(" inside
-                # the URL itself (e.g. .../Python_(programming_language)) so we
-                # don't silently truncate Wikipedia/Confluence-style links.
-                url = url_match.group(0)
-                _trailing = ".,;:!?)]}\"'"
-                while url and url[-1] in _trailing:
-                    if url[-1] == ")" and "(" in url:
-                        break
-                    url = url[:-1]
-                items.append(
-                    ActionItem(
-                        description=normalized,
-                        due_hint=due_hint,
-                        type="link",
-                        url=url,
-                    )
-                )
-            else:
-                items.append(ActionItem(description=normalized, due_hint=due_hint))
-        return items
+        return extract_action_items_from_body(body)
 
     def _build_draft(
         self,

hub/agents/python/email/gaia_agent_email/calendar_backend.py

@@ -24,6 +24,10 @@
 import httpx
 
 from gaia_agent_email.scopes import AGENT_NAMESPACED_ID, CALENDAR_SCOPES
+from gaia_agent_email.google_errors import (
+    access_not_configured_message,
+    access_not_configured_url,
+)
 
 from gaia.connectors.api import get_access_token_sync
 from gaia.connectors.errors import ConnectorsError
@@ -111,6 +115,11 @@ def _raise_http(self, response: httpx.Response, where: str) -> None:
                 "scopes were revoked. Reconnect Google in Settings → "
                 f"Connectors. (where: {where})"
             )
+        enable_url = access_not_configured_url(response)
+        if enable_url:
+            raise ConnectorsError(
+                access_not_configured_message("Calendar API", enable_url)
+            )
         raise ConnectorsError(
             f"Calendar API {where} returned {response.status_code}: "
             f"{response.text[:300]}"

hub/agents/python/email/gaia_agent_email/gmail_backend.py

@@ -53,6 +53,11 @@
     GMAIL_SCOPES,
 )
 
+from gaia_agent_email.google_errors import (
+    access_not_configured_message,
+    access_not_configured_url,
+)
+
 from gaia.connectors.api import get_access_token_sync
 from gaia.connectors.errors import ConnectorsError
 from gaia.logger import get_logger
@@ -434,6 +439,11 @@ def _raise_http(self, response: httpx.Response, where: str) -> None:
                 "scopes were revoked. Reconnect Google in Settings → "
                 "Connectors. (where: " + where + ")"
             )
+        enable_url = access_not_configured_url(response)
+        if enable_url:
+            raise ConnectorsError(
+                access_not_configured_message("Gmail API", enable_url)
+            )
         raise ConnectorsError(
             f"Gmail API {where} returned {response.status_code}: "
             f"{response.text[:300]}"