hermes-skills/skills/email/email-workflows/references/shonuff-inbox-monitoring-pattern.md

Sho'Nuff Inbox Monitoring — Collection + LLM Summary Pattern

Architecture

Two-tier hybrid: no_agent collection script + agentic cron for summarization.

Layer 1: Data collection (no_agent script)

Script at /root/.hermes/scripts/shonuff-inbox-collect.py — runs every 15m:

1. Connects to IMAP (shonuff@germainebrown.com)
2. Fetches UNSEEN messages
3. For each message NOT from trusted senders (g@germainebrown.com):
   • Extracts: sender, subject, date, body preview (first 500 chars)
   • Generates hash from Message-ID for dedup
   • Outputs JSON with messages array
4. Marks processed messages as \\Seen (prevents re-processing)
5. Silent (no output) when nothing new

Trusted senders filter: Trusted senders (user's own address) are skipped silently — no alert, no output.

Dedup: Uses hashed Message-ID in ~/.hermes/scripts/.shonuff-processed.json. This file persists across reboots. Each message reports exactly once.

Layer 2: Agentic cron job

Connected to the collection script via cronjob():

cronjob(action='create', name='shonuff-inbox-agent',
  schedule='every 15m',
  script='shonuff-inbox-collect.py',
  prompt='Check the collected inbox data above. If there are new messages in ShoNuff's inbox (shonuff@germainebrown.com), summarize each one for Germaine... respond with SILENT.',
  deliver='origin')

When collection script is empty

When the collection script exits with no output (no new messages), the agent receives an empty context. The prompt must include an explicit instruction: "If no new messages or only messages from trusted senders, respond with SILENT."

Key design choices

• Trusted sender list: Only the user's own email
• Body truncation: First 500 chars only
• Hash dedup: Prevents re-alerting on the same message
• Message-ID fallback: Falls back to IMAP sequence number when missing

Comparison to bounce-check

Aspect	shonuff-inbox-agent	bounce-check
Scope	All non-trusted senders	Only delivery-failure emails
Accounts	shonuff only	Both g@ and shonuff@
Output	JSON → LLM summarizes	Plain text count
Cadence	Every 15m	Every 60m
Cron type	Agentic (LLM)	no_agent

Pitfalls

• Message-ID is optional in the SMTP spec — duplicate alert risk
• IMAP UNSEEN state is sticky — if LLM call fails between collection and delivery, the message is silently lost. Consider pending-file for reliability.