​

Email Triage Agent

Date: 2026-04-17 Status: Planning (0% implemented) Milestones: v0.20.0 (Phase C1 — Inbox Companion), v0.23.0 (Phase C2 — Full Triage Agent) Related issues: #645 (Email Triage Agent), #663 (Daily briefs), #660 (Email & Calendar via MCP), #634 (Autonomy engine), #698 (Credential vault), #542 (Memory system), #701 (Configuration Dashboard) Related plans: Email & Calendar (parent plan), Autonomy Engine, Security Model, Agent UI, Setup Wizard Scope: This document specifies the Email Triage Agent as a two-phase deliverable. Phase C1 ships an on-demand inbox companion in v0.20.0. Phase C2 promotes it to a dedicated autonomous agent in v0.23.0. Integration is auto-discovered and hands-off — the agent detects the user’s email client, picks the right adapter, and walks through OAuth with minimum friction. Users enable/disable the whole integration with a single toggle in the Agent UI. This spec complements (and does not replace) the broader Email & Calendar plan.

​

TL;DR

• Codebase review (§2.5) confirmed ~95% of the plumbing exists: MCPClientMixin, DatabaseMixin, RAGSDK, TalkSDK, ApiAgent, Agent UI SSE, SummarizeAgent, and the MCP config stacking system are all reusable as-is. MVT is thin wrappers, not new plumbing.
• Gmail + Outlook come in via external MCP servers (no in-tree work for MVT).
• Slack output starts as a 50-LOC webhook POST (MVT) and graduates to a full Slack MCP + bot app in C2 — each slice is independently useful.

1. Local inference — email content never leaves the device.
2. Per-cohort autonomy (L0–L6 × 8 cohorts) rather than one global dial.
3. Auto-discovered integration — minimal hand-config.
4. Slack is a first-class output channel from day one.

• PR #606 or PR #517 M1 — memory system (pick one; they overlap)
• PR #517 M3+M5 — credential manager + scheduler (unblocks C2)
• PR #495 — security.py + write guardrails (pair with risk_tier extension)
• PR #622 — AgentOrchestrator (fixes routing)
• PR #779 — Agent Eval Toolchain (unblocks eval harness)
• Issue #741 — credential vault as standalone
• Issue #737 — Slack connector (covers our Slack auth path)

​

1. Executive Summary

1. Local inference. Triage, classification, summarization, and draft generation run on-device via Lemonade Server. Email content never transits a cloud inference endpoint.
2. Per-cohort autonomy. Users pick autonomy level per sender cohort — L5 for newsletters and L2 for colleagues is the common shape — not one global dial.
3. Auto-discovered integration. The agent detects installed email clients, infers the provider from domain, and walks through OAuth with minimum clicks.
4. Auditable by construction. Every action is logged, reversible at L4+, and the agent code is open-source.

​

1.1 Spec Status

• C1 is spec-level. Deliverables, effort estimates, and success criteria are detailed enough to drive an implementation plan.
• C2 is roadmap-level. Day estimates and a 29-item deliverable list exist so we know the scope, but C2 must be re-spec’d before implementation. Three C2 features (custom AI labels on local 4B, per-relationship voice learning, auto-follow-up quality) are research bets that need prototyping before lock-in. See §27 for what’s unvalidated.
• External claims (tool-call reliability percentages, MCP package statuses, phishing statistics) are cited from April 2026 research. They should be re-checked at implementation time.

​

1.2 Effort Envelope (Claude-Code-assisted)

1. Research-bet iteration is inherently serial — each user-review cycle waits.
2. Integration testing serializes at the end of each wave.
3. Human review bandwidth caps how many CC instances can actually make progress at once. 3–4 parallel instances is the practical ceiling per human.

​

1.3 Minimum Viable Triage (MVT) — ~1.5 Days CC-Assisted

• Auto-discovery of email clients — defer to C1. MVT assumes user enters email address (provider inferred from domain, ~1 hour).
• Agent Inbox HITL panel (§10/§12.6) — MVT shows agent suggestions inline in thread view, no separate inbox panel.
• Per-cohort autonomy sliders (§4.2) — MVT is L1–L2 only (query + per-message suggest); no autonomous actions.
• Custom AI Labels, Split Inbox tabs, Inbox-Zero mode — all deferred.
• Writing-voice per-relationship — MVT uses flat per-user voice (last 50 sent emails as few-shot, no relationship clustering).
• Speech-act classification T2a/T2b split — MVT uses single-prompt 4-bucket classifier (urgent / actionable / informational / low-priority). Speech-act ontology stays in the spec but is C1 polish, not MVT.
• In-tree Gmail MCP server — MVT uses taylorwilsdon/google_workspace_mcp. In-tree build is C2 only.
• 4-tier model cascade — MVT uses 2 tiers (T1 classifier, T3 on-demand draft). T0 deterministic + T2a/T2b splits are C1 polish.
• Credential vault, Configuration Dashboard, MemoryMixin — none exist yet; MVT works around them with plaintext config + SQLite ledger.

• ~6–8 h of CC authoring (tool mixin, classifier prompt, draft prompt, CLI wiring, React panel).
• ~2–3 h of human review and local iteration.
• ~3–4 h of OAuth live-account validation — the often-underestimated tax. Even with pre-built MCP servers, you spend real time approving scopes, confirming tokens refresh, and verifying per-provider behavior. This is serial human work and the single largest MVT risk.

​

2. Why This Spec Exists (Relative to the Broader Plan)

​

2.5 What We Already Have (Codebase Reality Check)

​

3. The “Whole Gamut” — Feature Inventory

​

3.1 Layer 1 — Ingest

​

3.2 Layer 2 — Understand

​

3.3 Layer 3 — Categorize

​

3.4 Layer 4 — Prioritize

​

3.5 Layer 5 — Act

​

3.6 Layer 6 — Learn

​

3.7 Layer 7 — Present

​

4. The Autonomy Spectrum

​

4.1 Levels

​

4.2 Cohorts

​

4.3 Design Principles

1. Levels gate actions, not understanding. Classification (topic + speech-act + priority), sender reputation, and entity extraction always run on every message. The autonomy level only decides what the agent is allowed to do with that understanding. At L0 the agent is silent; at L5 it can apply reversible actions autonomously. Nothing ever happens “behind the user’s back” without an audit-log entry.
2. Reversibility gates everything. Any action at L4+ must be reversible and logged in the undo ledger (see §9). Non-reversible actions (send, permanent-delete, block sender) require explicit user confirmation regardless of level.
3. Visibility over hiding. Microsoft’s Clutter → Focused Inbox arc proved that hiding mail invisibly breaks user trust faster than any accuracy gain wins it back. All categorized mail stays visible; agents re-rank and label, they never hide.
4. Per-cohort scoping. Global autonomy sliders are the wrong UX unit — users want L5 for newsletters while keeping L0 for cross-org. This is a headline differentiator because cloud products conflate privacy and autonomy. GAIA separates them: aggressive automation is safe because it is local and auditable.
5. Escalation available at every level. A panic control (“stop the agent, show me what it did”) is always accessible from the Agent UI tray and CLI.

​

4.4 Triage Buckets vs Content Categories

• Triage buckets (urgency-based, shown in UI) — Urgent / Actionable / Informational / Auto-archived. Derived from priority score (§3.4) + speech-act (§5) + cohort (§4.2). This is what drives Split Inbox tabs and the Daily Brief.
• Content categories (content-type-based, used by the classifier) — Primary / Newsletters / Notifications / Promotions / Receipts / Social / Custom AI labels (C2). Derived from T2 classification over sender + headers + body.

​

4.5 L6 Out of Scope

​

4.6 What “L5 Templated Auto-Send” Actually Means

1. Template source is explicit. The body comes from a user-authored template (stored in ~/.gaia/email/templates/) — never from free LLM generation. The LLM may fill declared slots with bounded generation:
   • Literal slots ({{requester_name}}): extracted entity only, no generation.
   • Bounded slots ({{greeting_tone: formal|casual}}): picked from a declared enum the user authored, not free text.
   • Single-sentence slots ({{ack_sentence: max=20_words, grounding=thread}}): LLM generates ≤ 20 words grounded in thread content, validated against a list of disallowed commitments (“I agree”, “I’ll pay”, “confirm”, etc.).
2. Recipient is in the same cohort as the trigger. Auto-reply to a newsletter → within-cohort. Auto-reply to a first-contact cold email → cross-cohort, requires confirmation (not L5).
3. Cohort is on a per-template allowlist. Each template declares which cohorts may trigger it. Default allowlist is empty.

• OOO auto-reply template triggered by any cohort during travel mode.
• “Got it, will review this week” template triggered by intra-org senders.
• “I only reply Tuesdays” template triggered by cross-org cold outreach.

• “Thanks, I agree to the terms” — contractual language.
• Any template that fills a slot with a free-generated sentence.
• Any template used across cohorts without the per-template allowlist.

​

5. Speech-Act Classification Layer

​

5.1 Ontology (Cohen-Carvalho, still the industry reference)

​

5.2 Implementation

• T2a — Label classifier. Emits speech_act, content_category, cohort, confidence. One-shot, no reasoning trace. Batched — up to 8 messages per call (single LLM invocation, structured array output). Skipping T2a entirely on messages T1 already labeled as bulk/promotional.
• T2b — Priority scorer. Emits priority_score (0–1), priority_reason (natural-language sentence), expected_response_window_hours. Runs only for messages T2a ranked above the trivial-triage threshold (skips newsletters and bulk promotions). Not batched — priority_reason quality degrades in batch mode; run one at a time.

• T1 filters down to ~120 classifier candidates (newsletters skipped).
• T2a = 120 ÷ 8 = 15 calls × 500 ms = ~7.5 s.
• T2b runs on ~40 messages (Urgent + Actionable) × 400 ms = ~16 s.
• Total classifier time: ~25 s. T3 drafts (P0 replies only) add another 20–40 s.

​

5.3 Pre-Processing Pipeline

​

6. Model Strategy: Four-Tier Cascade

1. Never call T3 without T0/T1 first. A 100-message inbox scan on a quiet morning should cost zero T3 tokens.
2. Hermes format is mandatory on Qwen3 backends — per Qwen’s function-calling docs. ReAct-style stopword prompts break Qwen3 mid-reasoning trace. Default the tool dispatcher to Hermes when the backend is Qwen3.*. The 97.5% reliability figure (jdhodges.com, April 2026) is a single-source claim; treat as hypothesis until validated by our eval harness.
3. T1 triage is the quota gatekeeper. It decides whether to load T3 at all. Batch T1 over multiple messages with structured JSON output.
4. Offline-capable. If Lemonade is unreachable, the agent degrades to T0-only mode (rule-based categorization). All cached data remains queryable.
5. Cold-start amortization. Keeping T1 warm (~600 MB RAM) is the right default for always-on triage — pay the 3s load once. T2 and T3 load on demand. See autonomy-engine.mdx §14 Open Question 1.

​

6.1 Email Content Never Routes to Cloud

• The tool wrapper that produces email content for the LLM tags the payload with routing_class="email_content".
• The hybrid router refuses to dispatch any payload with that tag to a non-local backend, regardless of complexity heuristics.
• The privacy indicator in the UI (§12.11) subscribes to hybrid-router events and flips red loudly if an email-content payload is ever seen heading to a cloud backend. This is the alarm, not the defense — the defense is the tag check.
• An integration test asserts this invariant on every PR touching gaia/llm/ or gaia/agents/chat/.

​

7. MCP Server Strategy

​

7.1 The GongRzhe Situation

​

7.2 Gmail Server — Decision Matrix

​

7.3 Outlook / MS Graph

• Primary: softeria/ms-365-mcp-server (200+ tools, MIT, active April 2026). This is the Outlook equivalent of the Gmail decision; the plan’s cited outlook-mcp-server was unverified.
• Auth: Microsoft Entra via MSAL. User authenticates once via browser popup; tokens refresh automatically and are stored in the credential vault (v0.23.0, §14) not env vars.

​

7.4 IMAP / Generic

• Fallback: codefuturist/email-mcp for IMAP providers outside Gmail/Outlook. 47 tools, IDLE watcher, presets — most complete generic option. Ships in Phase C2 only; Phase C1 is Gmail+Outlook-only to keep scope tight.

​

7.5 Pre-configuration in the MCP Settings Catalog

​

8. Tool Surface

Prerequisite: The @tool decorator currently accepts atomic: bool but not a risk_tier parameter (see §2.5). Before C1 ships, extend the decorator with risk_tier: Optional[Literal["read", "write", "destructive"]] and expose the value on _TOOL_REGISTRY[name]["risk_tier"]. Roughly 30 LOC plus a test file update. Until then, put destructive email tools (send_message, delete_message, batch_modify_labels) in the existing TOOLS_REQUIRING_CONFIRMATION set at src/gaia/agents/base/agent.py:38 as the interim gate.

​

8.1 Read Tools (risk_tier=“read”, auto-approve)

@tool(risk_tier="read")
def list_messages(query: str = "in:inbox", max_results: int = 50,
                  since: str = None) -> dict: ...

@tool(risk_tier="read")
def get_message(message_id: str) -> dict: ...

@tool(risk_tier="read")
def get_thread(thread_id: str) -> dict: ...

@tool(risk_tier="read")
def search_messages(query: str, max_results: int = 50) -> dict: ...

@tool(risk_tier="read")
def list_labels() -> dict: ...

@tool(risk_tier="read")
def get_attachment(message_id: str, attachment_id: str) -> bytes: ...

@tool(risk_tier="read")
def get_sender_reputation(sender_email: str) -> dict:
    """Return cached reputation: category, priority, response_history, corrections."""

​

8.2 Write Tools — Reversible (risk_tier=“write”, confirm or auto per cohort)

@tool(risk_tier="write")
def modify_labels(message_id: str, add_labels: list, remove_labels: list) -> dict: ...

@tool(risk_tier="write")
def archive_message(message_id: str) -> dict: ...

@tool(risk_tier="write")
def snooze_message(message_id: str, until: str) -> dict:
    """Snooze via `gaia/snoozed-until-<iso>` label + heartbeat wake-up task."""

@tool(risk_tier="write")
def create_draft(to: str, subject: str, body: str,
                 in_reply_to: str = None, cc: str = None) -> dict: ...

@tool(risk_tier="write")
def update_draft(draft_id: str, body: str) -> dict: ...

​

8.3 Write Tools — Destructive (risk_tier=“destructive”, always confirm)

@tool(risk_tier="destructive")
def send_message(draft_id: str) -> dict:
    """
    Sending is always destructive — never auto-executed even at L5 without explicit
    policy allowing it (templated sends only). Requires confirmation modal in UI,
    `y/N` in CLI. Claude Desktop's "draft only, never send" is the industry
    convention; GAIA matches it by default and only lifts the restriction under
    per-cohort policy for low-stakes templates.
    """

@tool(risk_tier="destructive")
def delete_message(message_id: str) -> dict:
    """Soft-delete (Trash); permanent delete not exposed."""

@tool(risk_tier="destructive")
def batch_modify_labels(message_ids: list, add_labels: list,
                        remove_labels: list) -> dict: ...

​

8.4 Extraction Tools (risk_tier=“read”, produce structured output)

@tool(risk_tier="read")
def extract_entities(message_id: str) -> dict:
    """Return dates, people, money amounts, URLs, phone numbers, OTPs."""

@tool(risk_tier="read")
def extract_action_items(thread_id: str) -> dict: ...

@tool(risk_tier="read")
def extract_meeting_request(message_id: str) -> dict: ...

@tool(risk_tier="read")
def extract_receipt(message_id: str) -> dict: ...

​

8.5 Cross-Agent Bridge Tools

@tool(risk_tier="write")
def create_calendar_event_from_email(message_id: str) -> dict:
    """
    In C1: directly calls the Google Calendar / MS Graph MCP server that is already
    connected via the Google Workspace / MS 365 adapters.
    In C2: routed through the dedicated CalendarAgent (created in v0.23.0) which
    adds conflict detection and attendee resolution.
    """

@tool(risk_tier="write")
def create_task_from_email(message_id: str, task_system: str = "default") -> dict: ...

@tool(risk_tier="read")
def index_for_rag(message_id: str) -> dict:
    """Adds message body + attachments to the local RAG index."""

​

9. Undo Ledger & Idempotency

​

9.1 Dual-Track State

1. Label marker (user-visible). Apply gaia/processed to every message the agent has seen; gaia/triaged-<date> for the specific triage run. Users can see these in Gmail’s UI at any time. Skipping is a single label-filter query.
2. SQLite ledger (source of truth). ~/.gaia/email/ledger.db stores richer state the label system can’t express — pending drafts, confidence scores, classification history, correction events, undo pointers.

​

9.2 Ledger Schema

CREATE TABLE message_state (
    message_id TEXT PRIMARY KEY,
    thread_id TEXT NOT NULL,
    account_id TEXT NOT NULL,
    processed_at TEXT NOT NULL DEFAULT (datetime('now')),
    speech_act TEXT,
    category TEXT,
    priority_score REAL,
    priority_reason TEXT,
    cohort TEXT,
    confidence REAL,
    draft_id TEXT,              -- FK if a draft was created
    triage_run_id TEXT,
    agent_version TEXT,
    model_used TEXT             -- which T1/T2/T3 combination
);

CREATE TABLE actions (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    action_id TEXT UNIQUE NOT NULL,     -- UUID for correlation
    timestamp TEXT NOT NULL,
    triage_run_id TEXT,
    message_id TEXT NOT NULL,
    action_type TEXT NOT NULL,          -- label_add, label_remove, archive, snooze, draft_create, send
    action_payload TEXT,                -- JSON — what was done
    reversal_payload TEXT,              -- JSON — how to undo
    reversed_at TEXT,                   -- null if not reversed
    autonomy_level INTEGER,
    autonomy_cohort TEXT,
    user_confirmed INTEGER DEFAULT 0
);

CREATE TABLE corrections (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    timestamp TEXT NOT NULL,
    message_id TEXT NOT NULL,
    original_category TEXT,
    corrected_category TEXT,
    original_priority_score REAL,
    corrected_priority_score REAL,
    feedback_source TEXT                -- drag, explicit-button, implicit-behavior
);

CREATE TABLE sender_reputation (
    sender_email TEXT PRIMARY KEY,
    first_seen TEXT NOT NULL,
    last_seen TEXT NOT NULL,
    message_count INTEGER DEFAULT 0,
    reply_rate REAL,
    avg_response_time_hours REAL,
    category TEXT,
    cohort TEXT,
    user_priority_override TEXT,        -- vip | muted | null
    last_correction TEXT
);

CREATE INDEX idx_actions_triage_run ON actions(triage_run_id);
CREATE INDEX idx_actions_message ON actions(message_id);
CREATE INDEX idx_message_state_triage_run ON message_state(triage_run_id);

​

9.3 Undo Protocol

• Single action: revert one ledger row.
• Triage run: revert all actions from a given triage_run_id. Users see “Undo morning triage (23 actions)” in the Agent Inbox.
• Time window: “Undo everything the agent did in the last hour.”
• Chat session: “Undo everything from this chat session.” Scoped by session_id from the Agent UI chat session (the only notion of “session” we have). Not applicable to autonomous runs — those are undone per triage_run_id.

​

9.4 Irreversible Actions

​

10. Agent Inbox — HITL Pattern

​

10.1 The Notify / Question / Review Triad

​

10.2 Agent Inbox API

# src/gaia/agents/email/inbox_api.py

class AgentInboxAPI:
    def list_pending(self, type: str = None, cohort: str = None) -> list: ...
    def approve(self, item_id: str, edits: dict = None) -> dict: ...
    def reject(self, item_id: str, reason: str = None) -> dict: ...
    def batch_approve(self, item_ids: list) -> dict: ...
    def undo(self, action_id: str) -> dict: ...

​

11. Auto-Discovery & Integration Onboarding

​

11.1 Discovery Pipeline (cheap-first, same cascade as triage)

• On first-run / setup-wizard step.
• When the user enables email integration for the first time.
• On explicit user request (“find my email accounts”).

• On a weekly heartbeat re-check (auto-engine Tier 0, zero-cost). Disabled by default; user opts in from Settings → Email → “Auto-detect new accounts weekly”.

​

11.2 Provider Inference From Email Domain

​

11.3 Hands-Off OAuth Flow

┌──────────────────────────────────────────────────────────────┐
│ 1. User clicks "Connect Gmail" in Agent UI (Settings)        │
│ 2. Agent loads pre-configured adapter for the provider       │
│ 3. Agent starts localhost OAuth callback on ephemeral port   │
│ 4. Agent launches system default browser with provider URL   │
│ 5. User approves at Google / Microsoft consent screen        │
│ 6. Callback captures code → agent exchanges for tokens       │
│ 7. Tokens stored (vault in C2, config in C1)                 │
│ 8. Initial sync begins (History API / deltaLink)             │
│    — progress bar shows "Indexing inbox" (< 60 s typical)    │
│ 9. Agent greets user with sample queries                     │
└──────────────────────────────────────────────────────────────┘

​

11.4 Zero-Config Defaults After First Connect

• Cohort rules from §4.2 defaults.
• VIP list from bidirectional signal: senders whom the user has both sent to AND received from in the last 90 days, weighted by (a) reply latency — faster reply = higher priority — and (b) thread depth. Purely one-way senders (vendors the user nags, newsletters) and cold inbound are excluded. Users can add/remove manually.
• Writing-voice few-shot corpus from the last 50 sent emails (C1) or last 300 (C2).
• Newsletter list from List-Unsubscribe header presence over a 30-day lookback.
• Default signature from the most recent sent email.
• User language & locale from OS settings + sent-items language distribution.
• Reply-window expectations per sender from observed response patterns.

​

11.5 Re-Discovery & Multi-Account

• Re-discovery runs weekly (heartbeat.yaml entry email_rediscover).
• If a new candidate appears (e.g., user adds a second Gmail to Outlook desktop), the agent posts a Notify to the Agent Inbox: “New account detected — [email protected]. Connect?”
• Multiple active accounts are supported in C1 (unified inbox view in C2).
• Disconnecting one account does not affect others.

​

11.6 Discovery Transparency

• CLI: gaia email discover --verbose prints the full candidate list with signal sources.
• UI: Settings → Email → “How we detected this” expandable panel shows provenance.
• No user content leaves the device during discovery. The only outbound network call is a DNS MX lookup (§11.2) to infer the provider from a domain — the DNS query carries no sensitive data and goes through the OS resolver. The local discovery log is never uploaded.

​

12. UI/UX Scope

​

12.0 Priority Index

• MVT P0 is the smallest set that lets a user say “summarize my inbox” and “draft a reply” and get useful results — that’s the demoable unit.
• C1 Polish P0 adds the quality signals (priority explanation, speech-act context, full auto-discovery) that make it feel professional.
• C2 P0 is the smallest set that makes it feel like a full triage agent (tabs, agent inbox, inbox-zero mode).

​

12.1 Onboarding & First-Run Experience

• Shows auto-discovered providers (§11) with account emails.
• One-click “Connect” per provider — triggers OAuth flow.
• Skip option (“I’ll set this up later”) with dismissible reminder.
• Empty-state fallback (“No email accounts detected — enter an email to get started”): user types email → provider inferred → OAuth.

• Three sample queries: “summarize my inbox,” “draft a reply to the latest from X,” “what’s urgent today?”
• Demonstrates the capability before the user has to explore.

​

12.2 Configuration Dashboard — Email Section

​

12.3 Daily Brief Panel

┌─ Daily Brief — Tuesday, April 17 ──────────────────────────┐
│                                                            │
│ 📬 Email — 23 new since last brief                         │
│   ├─ Urgent (2)                                            │
│   │  • [Boss] Q2 budget review due today      [open] [✓]   │
│   │  • [Client] Contract question             [open] [✓]   │
│   ├─ Actionable (4)                                        │
│   ├─ Informational (6)                                     │
│   └─ Auto-archived (11) ▸                                  │
│                                                            │
│ 📅 Calendar — 3 events today                                │
│   09:00 Team standup (15 min)                              │
│   11:00 Q2 budget review with Sarah (60 min)               │
│         → Prep: see attached budget from yesterday         │
│   14:00 1:1 with Alex (30 min)                             │
│                                                            │
│ ✅ Follow-ups                                               │
│   You owe 3 replies  ·  Awaiting 2 replies                 │
│                                                            │
│ [Start triage review]  [Read brief aloud]                  │
└────────────────────────────────────────────────────────────┘

• C1: Email section pulls from the email MCP adapter + T1/T2 classification. Calendar section pulls directly from the Google Calendar / MS Graph Calendar MCP (same adapter pack installed during email connect). No CalendarAgent class is required in C1.
• C2: Calendar section is mediated by the dedicated CalendarAgent (v0.23.0) which layers conflict detection and meeting-prep assembly on top. Follow-ups section is populated by the auto-follow-up detector.

​

12.4 Thread View

• One-line AI summary pinned above the thread; updates as new messages arrive.
• Priority badge (High / Normal / Low) with hover tooltip showing NL “why this?” (Outlook Copilot pattern).
• Speech-act badge — one of Request / Commit / Deliver / Propose / Meet / Amend / FYI (§5.1).
• Entity chips for extracted dates, people, money amounts — click → create calendar event, task, or contact.
• Draft panel at bottom. Visibility rules by cohort level:
  • L0: draft panel hidden.
  • L1: draft panel collapsed; “Draft a reply” button expands it on demand (user-initiated only).
  • L2+: draft panel always visible with a pre-generated draft ready to review; user can edit, tone-shift, or discard. Draft panel features:
  • Ghost-text autocomplete (Smart Compose style).
  • Tone selector (same / more formal / more casual / shorter / longer).
  • Voice dictation button (TalkSDK).
  • “Improve draft” button → T3 rewrite.
  • Send button (always confirms for external recipients).
• Activity strip on the right edge showing what the agent did on this thread (labels added, snoozed, drafts created) — each entry has an Undo link.
• Safety banner if the message is injection-flagged (red, persistent) or phishing-suspected — tools disabled for this message.

​

12.5 Split Inbox Tabs (C2)

• Default tabs: Urgent · Actionable · Informational · Auto-archived.
• User-defined AI label tabs appear alongside — Superhuman Custom Split Inbox pattern. The label’s natural-language prompt is editable inline from the tab header.
• Each tab shows unread count in a badge.
• Drag-to-train: user drags a thread to a different tab → agent updates the classifier and adjusts sender reputation (SaneBox pattern).
• Keyboard navigation between tabs: [/].

​

12.6 Agent Inbox Panel

• Batch-approve for same-cohort items: “Approve all 12 newsletter archives.”
• Per-item controls: Approve, Edit, Reject, Undo.
• Tool cards on each item show: what the agent proposes, confidence score, “why this?” reason, and the source message link.
• Per-run undo: “Undo morning triage (23 actions).”
• Morning brief’s “Start triage review” CTA feeds items here.

​

12.7 Inbox-Zero Guided Mode

• Full-screen single-thread view; distraction-minimized.
• Keyboard-first: e archive · r reply · s snooze · l label · . next · , back.
• Progress bar showing “12 of 47 threads.”
• End state: “Inbox Zero ✓” celebratory moment (subtle animation, muted haptic on touch devices).
• Adopts HEY’s Focus & Reply pattern and Superhuman’s Get Me To Zero.

​

12.8 Compose / Reply Experience

• Smart Compose ghost-text as the user types (Gmail pattern).
• Suggested reply chips above the compose box for short replies.
• Voice dictation → draft (TalkSDK) with real-time transcript.
• Tone rewrite — select text, choose new tone.
• Persistent “local processing” badge in compose — reassures users during generation.
• Signature auto-include from learned default.
• Confirm-before-send modal shows recipients (highlights cross-org in red), subject, and a “dry-run” summary of what’s being sent.
• Never auto-send without per-cohort-policy opt-in — default is always confirm.

​

12.9 Search Experience

• Natural-language query box (“emails from Sarah about the contract last month”).
• Results with citations — each hit shows the snippet that matched and the surrounding context (RAG-backed; see RAG SDK).
• Thread preview on hover.
• Filters — sender, date range, label, has-attachment, unread, cohort — composable with natural-language query.

​

12.10 Activity Feed Integration

• Filterable by agent type (agent:email).
• Triage runs collapse into a single entry with expandable per-message detail.
• Undo buttons attached to every reversible entry.
• Audit trail export includes email-agent actions (with bodies redacted by default; user can opt-in to include bodies for debugging).

​

12.11 Observability Surfaces

• “Why this?” tooltip on every agent-assigned category and priority.
• Model badge on every agent response showing which tier generated it (T1 / T2 / T3).
• Token-cost counter per triage run (informational — helps users see scale even though it’s $0 locally).
• Privacy indicator — persistent green check “All email processing local” anchored in the status bar; flips red and loud if hybrid routing is ever triggered for email (which should never happen — policy enforces local-only).

​

12.12 Empty & Error States

​

12.13 Keyboard Shortcuts (Superhuman-inspired)

​

12.14 Notifications

​

12.15 Voice-First Synergy (C2 + v0.21.0 Voice)

• Voice-drafted replies — activate mic, speak, TalkSDK → draft appears.
• Voice brief readout — Kokoro TTS reads the morning brief aloud.
• Voice queries — “what’s urgent?” / “what did Sarah say about the contract?”
• Voice approval during triage review (post-v0.23.0) — user can say “approve,” “skip,” “edit tone to friendlier.”

​

12.16 Accessibility

• Full keyboard navigation (§12.13) independent of mouse.
• Screen-reader labels on every interactive element; ARIA live regions for agent status updates.
• High-contrast theme support (reuses Agent UI theme system).
• Voice UI as a parallel input path for users who cannot use a keyboard.
• Configurable animation-reduction for vestibular sensitivity (respects OS prefers-reduced-motion).
• Minimum text sizes respected; no tiny chrome.

​

12.17 Mobile / Responsive (future)

​

12.18 MCP Settings & One-Click Integration

• #735 Connector Hub — parent epic.
• #736 Phase 1 — Catalog UI + Obsidian smoke test.
• #737 Phase 2 — Token-auth connectors: Slack / GitHub / Notion.
• #738 Phase 3 — OAuth device-flow + Playwright connectors.
• #714 Curated MCP server catalogue with one-click enable/disable.

​

12.18.1 The Catalog Card (per provider)

┌─────────────────────────────────────────────────────────────┐
│ [icon]  Gmail                               [Connect]  ⓘ    │
│         Read, label, draft, archive (local inference)       │
│         Status: Not connected                               │
│         Requires: gmail.modify scope                        │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ [icon]  Gmail · [email protected]       [Disconnect]  [⋮]    │
│         Read, label, draft, archive (local inference)       │
│         Status: ✓ Connected — last sync 2 min ago           │
│         Scopes: gmail.modify                                │
│         ┌────────────────────────────────────────────────┐  │
│         │ Enabled (toggle)                           [●] │  │
│         │ Auto-sync new accounts weekly (opt-in)     [○] │  │
│         │ Send scope (required for L5 templates)     [○] │  │
│         └────────────────────────────────────────────────┘  │
│         Tools registered: 12 (list_messages, search_…)      │
│         [How we detected this ▸]                            │
└─────────────────────────────────────────────────────────────┘

• Icon + provider name (Gmail, Outlook, Slack).
• One-line value prop so users know why they’d enable it.
• Status line — Not connected / Connecting… / Connected / Error (with actionable CTA — “Reconnect”, “Re-auth”, “Report issue”).
• Scope list — human-readable scope names (not raw OAuth scope strings).
• Primary action — Connect / Disconnect button.
• Per-provider toggle — Enabled on/off (disable without disconnecting).
• Advanced toggles — weekly auto-discovery rescan (§11.5), send scope opt-in (§14.4), per-cohort autonomy link.
• Tool count — how many MCP tools this provider registered.
• “How we detected this” disclosure (§11.6) — expandable provenance panel.
• ⋮ overflow — Rotate token, View audit log, Export config, Delete all data.

​

12.18.2 Connect-Flow Modal

1. Pre-flight check — detects whether the user has the MCP server binary cached, needs npx install, or needs a Python package. Shows a 1-line status.
2. Scope preview — lists each scope GAIA will request, in plain English. “Read emails” / “Create drafts” / “Apply labels”. The user approves the scope list before the browser opens (not just the provider’s consent screen).
3. Launch system browser — opens the provider OAuth URL in the default browser; shows a spinner + “Waiting for provider approval…” with a Cancel button.
4. Callback intercept — localhost ephemeral-port callback; completes automatically on success.
5. First-sync progress — progress bar for the initial History-API / Graph delta sync. Typical < 60 s.
6. Success state — “Connected ✓” + three sample queries as suggestion chips: “Summarize my inbox”, “What’s urgent?”, “Draft a reply to the latest from X”.

​

12.18.3 Discovery & Empty States

• Nothing connected: Big CTA “Connect your first email” with the auto-discovered candidates (§11.1) listed as pre-filled options.
• Manual entry fallback: always visible. User types an email address → domain-based provider inference (§11.2) → appropriate Connect flow fires.
• No candidates found: a single-line explainer + manual entry field, not a dead-end.

​

12.18.4 MCP Server Health Panel

• Server process status (running / exited / crashed).
• Last N tool calls with timestamps + duration.
• Recent errors with stderr tail.
• API quota consumption (Gmail units/sec budget per §15.1).
• “Restart server” button.

​

12.18.5 Bulk Actions

• “Disable all email integration” — single button at the top of the Email section. Equivalent to master toggle (§13.1) but visible here for users scanning for it.
• “Export my email config” — produces a JSON the user can version-control or migrate between machines. Tokens are redacted.
• “Delete all cached email data” — with double-confirm modal and scope preview (“This removes: 1,243 cached message summaries, 8 drafts in local ledger, sender reputation for 612 contacts. OAuth tokens are preserved”).

​

12.19 Output Formatting Grammar

​

12.19.1 Inbox Summary (Response to “Summarize my inbox”)

┌─ Inbox summary — 23 new since 8:42 am ─────────────────────┐
│                                                            │
│  🔥 Urgent (2)                                             │
│   • Sarah Chen — Q2 budget review due today        5 min   │
│     "Can you approve the attached before 2pm?"             │
│   • Acme Corp — Contract question                  22 min  │
│     "Quick clarification on clause 4.2"                    │
│                                                            │
│  📬 Actionable (4)                                         │
│   • PR #427 needs review (Alex)                    1h      │
│   • Follow-up on Feb 12 proposal (Jordan)          3h      │
│   • … 2 more ▸                                             │
│                                                            │
│  ℹ️ Informational (6)           [expand]                    │
│  🗃️ Auto-archived (11)          [expand]                    │
│                                                            │
│  [Start triage review]  [Draft replies]  [Read aloud]     │
└────────────────────────────────────────────────────────────┘

• Emoji prefix per bucket — 🔥 urgent / 📬 actionable / ℹ️ informational / 🗃️ archived — consistent across UI, Slack, and CLI (voice uses spoken names).
• Three lines per thread max — sender · subject · one-line summary · age.
• Collapsed low-priority buckets — informational and archived collapsed by default with expand affordance.
• Action strip at bottom — the obvious next actions, not a menu dive.
• No prose paragraphs — never respond with “You have 2 urgent emails from…” as free text. Always the card.

​

12.19.2 Tool Cards (Per-Action Agent UI Rendering)

┌─ archive_message          ✓ 120 ms   [undo]  [why?] ─┐
│   message_id: 18f…9a2                                 │
│   Because: classified as newsletter (cohort L5)       │
└───────────────────────────────────────────────────────┘

• Tool name + duration + result icon always visible collapsed.
• Undo link for reversible actions (§9.3) — one-click reverse.
• “Why?” link opens a popover with the classification reason (§5.2 priority reason) and the policy that authorized the action (cohort + level).
• Risk-tier ribbon — read = no ribbon, write = amber ribbon, destructive = red ribbon (§8 risk-tier work).
• Groups collapse — when the agent performs a triage run (e.g. 23 label actions), the cards collapse into a single “Morning triage · 23 actions · undo all” meta-card in the feed.

​

12.19.3 Thread View Headers

• Priority badge — colored pill (red / amber / gray) with number, not text; tooltip has the “why this?” sentence.
• Speech-act badge — verb-only, lowercase pill (request, propose, deliver). Links to §5.1 definitions on hover.
• Entity chips — pill shape, click-through to the creation action (calendar event / task / contact).
• Summary stripe — one-line block above first message, updates live as new messages arrive. Uses the same emoji prefix as buckets.

​

12.19.4 Draft Preview

• Provenance indicator — “Drafted by 35B · 4.2 s · grounded in 3 prior messages” — tiny text under the draft.
• Edit affordances — tone selector row, length slider, voice-dictate button.
• Send confirmation banner — recipient chips (cross-org recipients highlighted red per §14.5), subject, one-line dry-run summary of the send payload.
• Never a separate tab — inline editing in the thread view.

​

12.19.5 Daily Brief — Rich Format

• Email section — 4 buckets as above.
• Calendar section — next N events with a prep-note link per event.
• Follow-ups section — “You owe / They owe” columns with thread links.
• Optional News section — only if #669 (web search) is enabled.

• Fits on one screen without scrolling on a 1080p laptop.
• Printable — “Print” button produces a clean single-page PDF with the same grammar.
• Shareable — “Copy as markdown” produces the brief as plain markdown the user can paste into Slack or Notion (independent of the native Slack output channel in §12.20).

​

12.19.6 Classification Confidence Surfacing

• Amber outline around the bucket label or priority badge.
• “Review this” prompt in the activity feed.
• Don’t silently auto-act on low-confidence classifications — drop the cohort one level when confidence is below threshold (L4 → L3, L3 → L2).

​

12.19.7 Voice Output (C2, v0.21.0 voice integration)

• Bucket names spoken (“urgent”, “actionable”) — emoji are display-only.
• Thread titles truncated to first 8 words for speech.
• Interactive — user can say “skip” to advance, “more” to get the full summary.
• Uses TalkSDK with Kokoro TTS per §2.5.

​

12.20 Slack as an Output Channel

• User creates a Slack Incoming Webhook in their workspace (one-time, 2 min).
• User sets SLACK_WEBHOOK_URL via gaia email slack-setup or in the Agent UI Settings → Email → Slack.
• Agent posts Block Kit–formatted messages for:
  • Morning brief delivery (runs after local triage; user opts in per channel).
  • Urgent-message alerts (L4+ classified urgent → push within 30 s).
• Bodies are redacted by default in Slack — show sender + subject + one-line summary. Click-through link opens the message in the Agent UI thread view.
• No inbound from Slack. User still triages inside Gmail/Outlook or the Agent UI.

• Pre-configure a Slack MCP server template in mcp_servers.json alongside Gmail/Outlook. Candidates: @modelcontextprotocol/server-slack (Anthropic reference) or active community alternatives — decision in §24 Q15.
• Agent gains send_slack_message, read_channel, search_slack tools auto- registered via MCPClientMixin.
• User can DM GaiaAgent in Slack: “what’s urgent?” → agent queries local Gmail MCP, classifies, replies in-thread. This reuses the messaging-adapter restricted tool set (Security Model §12.2) — Slack DMs cannot trigger email sends without an explicit confirm in the Agent UI.

• Full Slack app (OAuth + Events API + Block Kit).
• Agent drafts a reply → posts to Slack with [Approve] [Edit] [Reject] buttons. Approve = send via Gmail MCP. Edit = opens thread in Agent UI. Reject = discard.
• Scheduled brief delivery via the autonomy engine (autonomy-engine.mdx) — runs T0/T1/T2 cascade, posts structured brief to Slack.
• Hooks into Agent Inbox (§12.6): Slack-driven approvals write to the same ledger as UI-driven approvals; undo works across both.

• Block Kit with sections for Urgent / Actionable / Informational / Archived.
• Plain-text fallback for narrow clients.
• Char limit: 4,000 per block, truncate long summaries with ”…” + click-through.
• Emoji prefixes for triage buckets (🔥 urgent, 📬 actionable, ℹ️ info, 🗃️ auto-archived).

• Slack token stored in credential vault (C2) or ~/.gaia/email/slack.json (chmod 600) for MVT/C1. Treated as a secret; log-redacted.
• Webhook URL is also a secret (anyone with the URL can post). Same storage and redaction rules.
• Workspace admin visibility — in managed workspaces, admins may see messages. The Settings UI warns users and recommends personal workspaces or a compliance review before enabling on work Slack. Bodies are redacted by default specifically because of this.
• Inbound Slack DMs are untrusted input — messaging-adapter restricted tool set applies. Slack DMs cannot trigger email sends, cannot invoke destructive tools, cannot bypass per-cohort autonomy policies.
• Rate limit: Slack web API allows ~1 msg/sec/channel. MVT brief + alerts are well under this; a 500-message triage run that alerted every message would not be. Urgent alerts are rate-limited to 5/hour per channel with a “…plus N more” summary.

• Per-channel toggle in Configuration Dashboard alongside Gmail/Outlook toggles.
• Disabling Slack only stops outbound; keeps email integration running.
• Master email-integration disable also stops Slack output.
• Travel mode (§13.4) silences Slack alerts but still delivers the morning brief (so the user sees accumulated email on return).

​

13. Enable / Disable & Runtime Controls

​

13.1 Master Toggle

• All email activity paused.
• MCP servers for email providers disconnected (processes terminated cleanly).
• Scheduled triage heartbeats paused.
• Email tools removed from the agent’s _TOOL_REGISTRY so the agent will not reference or attempt email actions even if asked.
• Cached ledger data retained for later reactivation.

​

13.2 Per-Provider Toggles

​

13.3 Runtime Pause / Resume

• CLI: gaia email pause, gaia email resume.
• Tray app: “Pause email triage” quick action.
• Keyboard: g then p (pause email).
• Pausing during an in-flight triage run lets the run complete cleanly but prevents scheduling new runs. Read-side tools remain available.

​

13.4 Travel Mode

​

13.5 Data Retention on Disable

• Keep local ledger for analytics / reactivation (default).
• Purge the ledger via Settings → Advanced → Retention (double-confirm modal).
• Export ledger + audit log (CSV / JSON) before purging.

​

13.6 Observable Kill Switch

​

13.7 Telemetry Transparency (opt-in, off by default)

• Triage throughput (messages / run), never content.
• Model tier usage distribution.
• Classifier accuracy trends (computed against user corrections).
• Error rates by provider.

​

14. Security & Threat Model

​

14.1 Indirect Prompt Injection (Primary Risk)

1. Channel separation. The LLM receives email content inside explicit “untrusted content” wrappers. The system prompt instructs the model never to treat content inside these wrappers as commands.
2. Tool allowlist per invocation. When processing email content, the classifier (T2) is bound to only the classification tool; it cannot invoke send_message or cross-account tools. The draft generator (T3) is bound only to create_draft — not send_message.
3. Deny body-initiated external-recipient actions. No email body may cause the agent to send, forward, or CC outside the user’s organization without a confirm modal — even at L5. Cross-org recipient = forced confirmation.
4. Prompt-injection detection. Hidden content stripping before T1/T2 (zero-width characters, color-on-color text, font-size-0 text, suspicious data: URIs). Inbox-Zero’s defense-in-depth patterns (April 2026) are the reference.
5. Schema-validated output. T2 outputs must validate against a strict JSON schema with no free-form command fields.

​

14.2 AI-Generated Phishing

• Sender-auth failures (SPF/DKIM/DMARC headers).
• Homoglyph domains (goog1e.com, amaz0n.com) via Unicode normalization + Punycode inspection.
• First-contact senders whose message contains urgency + payment/credential asks.
• Display-name mismatch (From: "IT Support" <[email protected]>).

​

14.3 Credential Security

• OAuth tokens stored in the encrypted credential vault (Security Model §7), not environment variables, not plain JSON.
• Platform-appropriate backing: DPAPI (Windows), Keychain (macOS), Secret Service (Linux).
• Tokens never logged, never appear in audit trail, never sent to cloud endpoints.

​

14.4 OAuth Scope Strategy (Least Privilege)

​

14.5 Data Leak Prevention

• Agent responses are scanned for PII leakage before being returned to messaging adapters (Discord/Slack/Telegram). The existing PII redaction in Security Model §12.3 applies.
• Email content never leaves the device for inference. If hybrid-routing sends any task to a cloud model, email content is explicitly blocked from that routing by policy — and the persistent UI privacy indicator (§12.11) flips loud if this invariant is ever violated.
• Audit log redacts message bodies by default; sender addresses are shown; full bodies are accessible only from the local SQLite directly.

​

14.6 Autonomous Action Boundaries

• Can the agent autonomously send to a recipient outside a user-approved cohort.
• Can the agent forward or CC an external recipient without explicit confirmation.
• Can an email body trigger a shell command, file write, or MCP tool outside the messaging/calendar/task allowlist.
• Can the agent process emails during quiet_hours if the user has disabled it.

​

14.7 Residual Risk

• Novel injection patterns. Attackers will invent encodings we don’t detect (new homoglyph sets, steganographic payloads in HTML styles, injection via attachment content passing through the VLM). We accept this and commit to a rapid-patch posture.
• Classifier jailbreak via persuasion. A well-crafted business email can convince the classifier to label it “urgent + from boss” and the drafter to produce a persuasive reply to the attacker. The L5 template constraint (§4.6) is the structural defense — LLM-free generation cannot be persuaded into novel content.
• Token exfiltration via timing. An attacker sending many crafted emails could infer OAuth token contents from response-timing variations. We don’t defend against this beyond normal TLS — out-of-scope for this release.
• Supply chain for MCP packages. If taylorwilsdon/google_workspace_mcp or softeria/ms-365-mcp-server is compromised upstream, the attacker has the user’s tokens. Mitigated by the in-tree Gmail MCP in C2 (§7.2) and by package checksum verification (Security Model §5.3).
• User confusion as attack vector. If the UI shows a drafted reply the user is pressured to send quickly, the user may approve without reading. The confirm-before-send modal (§12.8) is necessary but not sufficient — long-term mitigation is training the user through consistent “why this?” explanations.

​

15. Gmail API & Rate-Limit Strategy

​

15.1 Quota

• 250 units/user/second (soft); 1B units/day (hard).
• send_message = 100 units (40x a messages.get at ~5 units).
• messages.list + messages.get loop on a 500-message inbox burns through the per-second quota.

​

15.2 Strategy

1. History API for incremental sync. After the initial backfill, poll users.history.list with the last-seen historyId to fetch only deltas. This is the single highest-leverage optimization and it is under-used in OSS agents.
2. Batch reads. users.messages.batchGet with up to 100 IDs per call. A full inbox scan of 1,000 messages → 10 API calls instead of 1,000.
3. Local message cache. Already-processed messages stay cached in the ledger; re-triage loads from cache, not API.
4. Exponential backoff with jitter on 429. Truncated exponential backoff; add ±25% jitter to prevent thundering herd across heartbeat runs.
5. Target 150 units/sec (60% of the hard limit) to leave headroom for user-initiated actions.
6. Per-second token bucket tracked locally; not reliant on Google’s headers.
7. Send path is special. Drafts are always cheap; sends are always 100 units. Bulk-send is rate-limited in the agent, not just the API.

​

15.3 Outlook / MS Graph Differences

• Graph quota is throttling-based, not unit-based — 10,000 requests per 10 minutes per app, per tenant.
• Use @odata.deltaLink for incremental sync (Graph’s equivalent of History API).
• Batching via $batch endpoint (up to 20 requests per batch).

​

16. Phase C1 — Inbox Companion (v0.20.0)

​

16.1 Shape

​

16.2 Deliverables

• Human-only — a mid-level engineer writing the code manually.
• CC-assisted — same task executed with Claude Code doing the bulk authoring, a human reviewing each chunk, and eligible rows dispatched to parallel CC instances where marked ”║” (see §16.2.1).

• Human-only: ~17 days sequential, ~3.5 weeks with review.
• CC-assisted (single instance, human reviewer): ~6 days wall clock.
• CC-assisted + 3-way parallel: ~3.5 days wall clock (limited by integration testing, OAuth validation with real providers, and eval-fixture iteration which remain serial).

​

16.2.1 Parallelization Strategy (Claude Code)

1. Wave 1 — Foundation (parallel, ~0.5 d wall): rows 1 (3 platform subtasks in parallel), 2, 3+4 (same MCP config pattern).
2. Wave 2 — Tools & UI plumbing (parallel, ~0.5 d wall): rows 5+6 (same Dashboard area), 7, 8+13.
3. Wave 3 — Classifier iteration (serial, ~1 d wall): rows 9+10 with eval-fixture feedback loops.
4. Wave 4 — UX surfaces (parallel, ~0.6 d wall): rows 11, 12, 14+15, 16.
5. Wave 5 — CLI + tests + docs (parallel, ~0.5 d wall): rows 17+18+22, 19 (per-module parallel), 20, 21.

• OAuth with live Gmail/Outlook test account (one human, real browser).
• Eval-fixture prompt iteration — needs human judgment per iteration.
• Integration review — one senior reviewer validating the whole slice before ship.
• Injection red-team — adversarial fixture design is a creative task; CC can generate candidates but a human picks and ranks.

​

16.3 Explicit Non-Goals for C1

• No scheduled triage runs (needs autonomy engine).
• No auto-archive / auto-label (needs undo ledger at write-side).
• No auto-follow-up detection (needs scheduled runs).
• No write actions at L3+ (L1 and L2 only — user approves every write).
• No IMAP / generic email providers (Gmail + Outlook only).
• No custom AI labels (deferred to C2 — requires Split Inbox UI).
• No meeting-prep assembly (deferred to C2 — requires heartbeat).
• No in-tree Gmail MCP server (deferred to C2).
• No Inbox-Zero guided mode (basic keyboard nav ships; full mode in C2).
• No Agent Inbox panel (L1/L2 suggestions shown inline in thread view instead).
• No travel mode (C2).

​

16.4 C1 Success Criteria

• User can say “summarize my inbox” → agent returns 4-bucket triage view with top-5 urgent threads + one-line summaries, in < 10 seconds on a typical inbox.
• User can say “draft a reply to this” → agent produces a draft matching user voice (few-shot from sent items), draft stored in Gmail drafts folder — never sent.
• User can open the Daily Brief panel → morning/evening digest renders with email + calendar sections.
• User can toggle email integration off → all email tools disappear from the agent within 5 seconds; re-enabling restores them.
• Auto-discovery finds the user’s primary account on first run in ≥ 80% of cases (Win + macOS). Manual entry always works.
• Classification correction: user re-categorizes a message → memory updates → next similar message is classified correctly (verify via eval fixture).
• Zero outbound network calls with email content (verify via audit log scan).

​

17. Phase C2 — Full Email Triage Agent (v0.23.0)

​

17.1 Shape

​

17.2 Deliverables

• Human-only: ~42 days sequential, ~8.5 weeks with review.
• CC-assisted (single instance, human reviewer): ~15 days wall clock.
• CC-assisted + 4-way parallel (4 CC instances, 1 human reviewer): ~8 days wall clock. The limit is no longer CC throughput but human review capacity and the three research-bet rows (#7, #8, #9) where iteration with the user is inherently serial.

​

17.2.1 Parallelization Strategy (Claude Code)

1. Wave 1 — MCP server + agent shell (~2 d wall): rows 1, 2+3 concurrent, 17 (IMAP) in parallel.
2. Wave 2 — Research-bet prototypes (~2 d wall, iteration-gated): rows 7, 8, 9 spiked simultaneously; user reviews after each iteration. These may terminate early or expand based on outcomes.
3. Wave 3 — Autonomy + UI (~1.5 d wall): rows 4, 5+6, 10, 11, 12+13, 14 (per pipeline in parallel).
4. Wave 4 — Hardening (~1 d wall): rows 15, 18+21, 19, 20, 22, 23, 24, 25.
5. Wave 5 — Polish + release (~1.5 d wall): rows 26, 27, 28, 29.

• Research-bet iteration (rows 7/8/9).
• Red-team fixture authoring (row 19).
• Live Gmail test account validation for the in-tree MCP (row 1).
• Screen-reader manual pass (row 27).

• Row 7 → drop auto-follow-up draft generation; ship follow-up detection only, draft is user-authored via “reply” command.
• Row 8 → drop per-relationship; ship single per-user voice.
• Row 9 → drop custom AI labels; ship only the default Split Inbox tabs.

​

17.3 C2 Success Criteria

• Accuracy: > 85% triage-category agreement with user corrections after 2 weeks of use (measured via corrections table).
• Draft acceptance: > 50% of generated drafts sent without edit, > 80% sent with minor edit.
• Latency: < 60 seconds for a 500-message morning triage run on a typical developer laptop (Ryzen AI 300 series).
• Quota: < 60% of Gmail’s 250 units/sec budget during peak.
• Security: 0 outbound calls with email content (verified continuously); 0 body-initiated external actions (verified via red-team fixtures).
• Undo: 100% of L4+ actions reversible via a single API call; full triage run reversible as a batch.
• Offline: Core categorization + drafts work with Lemonade reachable + Gmail unreachable (uses cached ledger).
• Reliability: T2 Hermes-format tool dispatch succeeds in ≥ 97% of cases on Qwen3.5-4B-GGUF (matches jdhodges.com April 2026 benchmark).
• Auto-discovery: Finds the user’s primary email account without manual entry in ≥ 90% of cases on Windows + macOS.
• Enable/disable: Full integration disable completes within 5 s; no dangling processes; cached data preserved; re-enable is seamless.

​

18. Data Model Summary

​

19. CLI Commands

​

19.1 Phase C1

gaia email discover                       # Run auto-discovery now
gaia email discover --verbose             # Show all signal sources
gaia email connect --provider gmail       # OAuth setup flow
gaia email connect --email [email protected] # Provider inferred from domain
gaia email inbox                          # Summarize current inbox (on-demand)
gaia email summarize <message_id>         # Summarize a thread
gaia email draft --reply-to <message_id>  # Generate a draft reply
gaia email brief                          # Today's brief (morning/evening auto-select)
gaia email search "contract renewal"      # Semantic search
gaia email pause / resume                 # Runtime pause/resume
gaia email status                         # Connection + cohort counts + last triage
gaia email enable / disable               # Master toggle
gaia email slack-setup                    # Configure Slack webhook URL (§12.20 MVT)
gaia email brief --to slack               # Send today's brief to Slack now

​

19.2 Phase C2 (adds)

gaia email triage                         # Run a triage pass now
gaia email triage --dry-run               # Preview actions without applying
gaia email policy list                    # Show per-cohort autonomy levels
gaia email policy set --cohort newsletters --level 5
gaia email labels create --name "Investors" --prompt "Emails from investors about fundraising"
gaia email labels list
gaia email undo --run <triage_run_id>     # Reverse a triage run
gaia email undo --action <action_id>      # Reverse a single action
gaia email followups                      # List pending follow-ups and auto-drafts
gaia email unsubscribe --sender <sender>  # Triggers List-Unsubscribe
gaia email travel-mode --until 2026-05-01 # Travel mode
gaia email eval                           # Run the classifier eval harness
gaia email slack-connect                  # Install Slack app (C2 bot, OAuth2)
gaia email slack-test                     # Send a test message to verify delivery

​

20. OpenAI-Compatible API Surface (C2)

POST /v1/email/triage                { dry_run: bool, cohorts: [...] }
POST /v1/email/brief                 { date: iso, readout: voice|text }
POST /v1/email/search                { query: str }
POST /v1/email/draft                 { message_id, tone?, length? }
POST /v1/email/classify              { message_id }
GET  /v1/email/actions               { since, triage_run_id? }
POST /v1/email/undo                  { action_id | triage_run_id | since }
GET  /v1/email/policy
PUT  /v1/email/policy                { cohort, level }
GET  /v1/email/discovery             # Candidate list
POST /v1/email/connect               { provider, email }
POST /v1/email/disable               # Master disable
POST /v1/email/enable                # Master enable

​

21. Testing Strategy

​

21.1 Unit Tests

• Classifier: fixture of 200 emails spanning all cohorts × speech acts; expected labels + tolerances. Run on every PR.
• Draft generator: golden-file tests for “user voice” — takes a synthetic sent-items corpus, generates drafts, verifies tone signals (formality, sign-off, length distribution).
• Ledger: undo round-trip — apply action, undo, assert state equivalence.
• Discovery: mock OS signals per platform; verify correct adapter is picked across 20+ combinations.
• Prompt-injection fixtures: 50 adversarial emails with hidden commands; classifier must ignore all of them; dispatcher must bind to classification tool only.

​

21.2 Integration Tests

• Mocked Gmail: tests/mcp/test_email_triage.py with a Gmail API mock server serving canned message lists. Tests full triage run, undo, idempotency, disable.
• Live Gmail (opt-in): tests/integration/test_email_live.py marked @pytest.mark.slow — uses a dedicated test Gmail account; reads + drafts only (no sends).
• Quota test: simulate 1,000-message inbox, verify triage pass stays under 150 units/sec.
• Disable/enable cycle: exercise toggle 100 times; assert no resource leaks.

​

21.3 Eval Harness

• Triage accuracy (per cohort).
• Draft acceptance rate (simulated correction feedback).
• Classifier stability under model version bumps.
• Latency percentiles (p50/p95/p99) on fixed fixture size.
• Auto-discovery: platform-specific fixtures for Win/macOS/Linux.
• Security: red-team fixtures with injection attempts must produce zero tool calls outside the classification allowlist.

​

21.4 UX Tests

• Keyboard shortcut coverage in Playwright MCP tests.
• Accessibility audit (axe-core) against all email-agent UI surfaces.
• Screen-reader smoke test (VoiceOver on macOS, NVDA on Windows).

​

22. Dependencies

​

22.1 Dependencies for MVT (§1.3) — ~1.5 days

• MCPClientMixin + config stacking (src/gaia/mcp/mixin.py) — Exists
• DatabaseMixin (src/gaia/database/mixin.py) — Exists
• Agent + @tool + _TOOL_REGISTRY — Exists (with the risk_tier caveat in §8)
• ApiAgent mixin + OpenAI-compatible server — Exists
• Agent UI SSE + React component system — Exists
• SummarizeAgent (reuse for thread summaries) — Exists
• JiraAgent / DockerAgent (reference patterns) — Exists

​

22.2 Dependencies for C1 Polish (beyond MVT)

​

22.3 Dependencies for C2

​

22.4 Outstanding PRs & Issues to Address First

​

22.4.1 Tier 1 — High-Impact, Land Before Implementation Starts

​

22.4.2 Tier 2 — Strongly Helpful, Land in Parallel with Implementation

​

22.4.3 Tier 3 — Synergistic, Not Blocking

​

22.4.4 Conflict: Two Memory PRs in Flight

​

22.4.5 Recommended Landing Sequence

1. Resolve the memory conflict (§22.4.4) — pick #606 or #517 M1; close the other.
2. Land PR #495 (security.py + guardrails) — small, close to ready, unblocks risk_tier.
3. Add risk_tier to @tool as a follow-up to #495 (~30 LOC, ~1 h CC).
4. Land PR #779 (Agent Eval Toolchain) — unblocks our eval harness.
5. Land PR #622 (AgentOrchestrator) — fixes routing foundation.
6. Land whichever memory PR won (§22.4.4) — unblocks VIP/correction/preference learning.
7. Pick up #741 (credential vault standalone) — unblocks token storage.
8. Land PR #517 M3/M5 if not already rolled in — unblocks C2 autonomy.
9. Land PR #718 (MCP reliability tests) — unblocks our MCP integration test suite.
10. Start email triage MVT implementation — at this point, most workarounds in §22.1–§22.3 are no longer needed.

​

22.5 Synergies (not blockers, but amplify value)

• #702 Voice-first (v0.21.0) — voice brief readout, voice-drafted replies.
• #700 Meeting notes (v0.21.0) — feeds meeting-prep assembly.
• #704 Personal CRM (v0.24.0) — supplies per-contact tone signals.
• #635 Messaging adapters (v0.23.0) — deliver daily brief via Signal/Telegram.

​

23. Success Metrics

​

24. Open Questions

​

25. Implementation Sequence

1. Auto-discovery signal collectors per platform.
2. Provider inference + MX lookup.
3. Pre-configured MCP server templates (Gmail, Outlook).
4. Configuration Dashboard email section + master toggle + per-provider cards.
5. Settings UI Connect flow → OAuth tokens land in config (vault migration in C2).
6. Tray observable kill switch + CLI pause/resume.
7. email_tools.py mixin with read tools + create_draft.
8. T1 + T2 classifier prompts; speech-act output schema.
9. T3 summarizer + draft generator with sent-items few-shot.
10. Sender-reputation cache (read-path only; no write actions yet).
11. Daily Brief panel (on-demand, Agent UI).
12. Thread-view enhancements (badges, entity chips, activity strip).
13. Keyboard shortcuts for thread view.
14. GaiaAgent memory integration for VIPs and corrections.
15. gaia email CLI subcommands (C1 set).
16. Tests: unit, MCP-mocked, discovery fixtures, injection.
17. Documentation.

1. In-tree Gmail MCP server with History API + rate limiting.
2. EmailTriageAgent class; ledger schema + write-side tools.
3. Undo protocol + Agent Inbox backend.
4. Per-cohort policy engine.
5. Autonomy engine integration (scheduled triage heartbeat task + re-discovery task).
6. Writing-voice learning (per-relationship).
7. Custom AI labels + Split Inbox UI.
8. Priority scoring with “why this?”.
9. Auto-follow-up.
10. Extraction pipelines (receipts, calendar, tasks, OTPs, travel).
11. Bulk unsubscribe via RFC 8058.
12. Meeting-prep assembly (Calendar + RAG).
13. IMAP fallback via codefuturist/email-mcp.
14. Agent Inbox UI panel.
15. Inbox-Zero guided mode + full keyboard shortcuts.
16. Travel mode + telemetry transparency.
17. Prompt-injection hardening.
18. Credential vault migration.
19. OpenAI-compatible API endpoints.
20. Agent Registry registration.
21. Voice-first integration.
22. Accessibility audit.
23. Eval harness + red-team fixtures.
24. Documentation + SDK reference.

​

26. Non-Goals for Both Phases

• Apple Mail / CalDAV (no browser UI, and Apple’s ecosystem is low-priority for AMD hardware). Deferred indefinitely.
• On-device training of classifier weights. Fine-tuning lives in the v0.19.0 model quality stream; the agent consumes the produced LoRA adapters, it does not train.
• Full MTA — the agent is a client, not an email server. It never bypasses Gmail or Outlook’s send pipeline.
• Desktop Outlook via COM. The broader plan’s §7.1 recommendation stands: skip COM — too fragile, Windows-only. MS Graph covers both Outlook Web and Outlook Desktop accounts.
• Email-side encryption (S/MIME signing or PGP encryption for outbound). Pass-through of encrypted inbound is in §24 Q9; agent-generated encryption is out of scope.
• Cross-tenant multi-user shared-inbox (L6). Deferred to a future phase because it requires compliance contracts and audit guarantees beyond what a local desktop agent can certify.
• Mobile companion app. The Agent UI is desktop-first; §12.17 explicitly designs the data model to not preclude mobile, but no mobile deliverable ships in C1 or C2.

​

27. Known Weaknesses, Unvalidated Claims, Decision Debt

​

27.1 Unvalidated Claims Cited as Fact

​

27.2 Research Bets, Not Engineering Certainties

1. Custom AI Labels on local 4B. Superhuman Auto Labels run on frontier cloud models. Matching parity with Qwen3.5-4B is an open research question. Spike: 20-label fixture × 100 messages, measure precision/recall, before committing UI surface.
2. Writing-voice learning per-relationship. With a 50-exemplar budget (C1) divided across N relationships, each gets ~5 exemplars — below useful. Either (a) budget-up to 300 (C2 already) and pool across similar relationships, (b) use embedding retrieval to pull the N nearest exemplars per draft, or (c) drop “per-relationship” and settle for per-user voice. Prototype first.
3. Auto-follow-up draft quality. “Hey, following up on my email from 5 days ago” is one of the highest-visibility actions the agent takes. If the draft quality is wrong, users lose trust fast. Needs a dedicated eval before shipping.
4. Speech-act accuracy on 4B. Cohen-Carvalho classifiers from 2004 ran on hand-crafted feature extractors with 0.72-0.85 kappa. Achieving comparable accuracy zero-shot on 4B is plausible but unvalidated. Eval fixture first.
5. Meeting-prep assembly quality. Pulling email + calendar + docs into a pre-meeting brief requires cross-source grounding the 35B model may not do well. High-variance deliverable; candidate for C3 if it doesn’t ship cleanly.

​

27.3 Decision Debt

• JMAP MCP server selection (§11.2) — 7+ alternatives, no pick.
• Which fork of Gmail-MCP in C1 — we chose taylorwilsdon/google_workspace_mcp but the active forks of GongRzhe may be a better fit depending on fork health at implementation time.
• Classifier model versioning. If we bump Qwen3.5-4B → Qwen4-4B mid-cycle, all cached classifications have unknown distribution shift. No migration strategy specified.
• Correction retraction. User corrects classification → classifier learns. If the correction was itself wrong, there’s no “I take that back” mechanism. corrections table needs a retracted_at column.
• Eval fixture ownership. Who curates the 200-message fixture? Is it shipped with the repo? Synthetic vs real? PII handling?
• Multi-language strategy. Pre-processing detects language (§5.3); what the classifier does with non-English at 4B is unspecified.
• Attachment-content in RAG privacy. When index_for_rag pulls a message into the RAG index, the user’s semantic search indexes their own email. If the RAG index is exported for debugging, bodies leak. Retention + export policy needed.
• L5 template storage sync. Templates in ~/.gaia/email/templates/ — cross-device sync not specified.

​

27.4 Over-Scoped Areas

• C2 effort estimates. 29 deliverables × day-level estimates for work 2 months out is finer than usually warranted. In the Claude-Code-assisted world (§1.2), the scope is more achievable than it looks on paper — the concern shifts from “can we staff this?” to “is this the right scope?”. Re-spec before C2 starts remains the recommendation.
• UI surfaces. §12 lists 17 surfaces. Even with CC-assisted velocity, shipping all of these in C2 means a lot of surface to maintain. The §12.0 priority index guides trimming; half the P2 items could be deferred without loss.
• API surface (§20). 13 endpoints may be more than needed. API exposure should be driven by consumer demand, not spec completeness.

​

27.5 Under-Scoped Areas

• Migration / upgrade. Ledger schema changes between releases. No migration framework specified.
• Team / small-business L4-L5 path. Roadmap positions SMB as Tier 3 audience. Spec defers L6 (shared inbox) but doesn’t address multi-user at lower levels.
• Telemetry schema. §13.7 mentions opt-in telemetry categories but doesn’t define the schema or transport.
• Quota for Outlook / Graph. §15.3 covers it in two sentences. Production quality needs per-tenant throttle tracking.
• Failure-injection testing. Tests cover happy paths + adversarial emails, but not MCP server crashing mid-triage, Lemonade OOM, vault corruption.

​

27.6 Open Debates Worth Resolving Before Implementation

1. Should we ship any of this at v0.20.0 or roll it all into v0.23.0? (Pro-v0.20.0: milestone commits to “Email + Calendar via MCP” already, and CC + 3-way parallelism brings C1 wall-clock to ~3.5 days. Con-v0.20.0: v0.20.0 is already loaded with 10 other deliverables.)
2. Is the 4-tier model cascade the right default or is 3-tier (drop T1) simpler and good enough?
3. Should the agent be called “Email Triage Agent” or something more aspirational? Current name is accurate but dry.

​

28. References

• Email & Calendar Integration (parent plan)
• Autonomy Engine
• Security Model
• Agent UI
• Messaging Integrations
• Setup Wizard
• Agent System SDK
• MCP Client SDK

• Superhuman Mail AI — Split Inbox, Auto Labels, Auto Drafts, Ask AI
• Shortwave AI Assistant — Bundles, Ghostwriter, cross-thread reasoning
• Fyxer AI — Autodraft, meeting-note integration, 300-email voice learning
• SaneBox — SaneLater/SaneBlackHole, drag-to-train
• Spark Mail +AI — Smart Inbox, My Writing Style
• Gmail Gemini integration — AI Inbox, Smart Compose
• Outlook Copilot — Prioritize My Inbox — priority with natural-language reason
• HEY — Imbox / Feed / Paper Trail, Reply Later + Focus & Reply
• Missive AI Rules — shared-inbox team prompts

• langchain-ai/agents-from-scratch — HITL email reference
• langchain-ai/ambient-agent-101 — notify/question/review triad, Agent Inbox
• elie222/inbox-zero — Reply Zero, Cursor Rules for email, prompt-injection defense
• GongRzhe/Gmail-MCP-Server — archived March 2026; tool-surface reference
• taylorwilsdon/google_workspace_mcp — C1 primary
• softeria/ms-365-mcp-server — Outlook primary
• nspady/google-calendar-mcp
• codefuturist/email-mcp — IMAP fallback with IDLE

• Whittaker & Sidner, “Email Overload” (CHI 1996)
• Bellotti et al., “Taking Email to Task” / Taskmaster (CHI 2003)
• Aberdeen, Pacovsky & Slater, “Gmail Priority Inbox” (NIPS 2010)
• Cohen, Carvalho & Mitchell, “Learning to Classify Email into ‘Speech Acts’” (EMNLP 2004)
• Vellum, “Levels of Agentic Behavior”
• Knight Institute, “Levels of Autonomy for AI Agents”

• Gmail API quota
• Nylas — Gmail API limits for AI agents
• Local-LLM tool-calling eval (jdhodges.com, April 2026)
• Qwen function-calling docs (Hermes format)
• RFC 8058 — One-click List-Unsubscribe

• Agentic AI Security Survey (arXiv 2510.23883) — EchoLeak, indirect prompt injection
• OWASP LLM Top 10 — LLM01: Prompt Injection