Email Agent Runbook

Email Agent Runbook 

 Service: Email Agent Daemon 
 Location: ~/system/daemons/email-agent.js 
 LaunchAgent: com.john.email-agent 
 Interval: Every 5 minutes (300s) 
 Last Updated: 2026-04-15 

 

 1. Architecture 

 What It Does 
 The Email Agent is a 24/7 daemon that: 
 
 Fetches unseen emails from 6 IMAP accounts every 5 minutes 
 Classifies emails using VIP bypass → quick filter → Ollama (llama3.1:8b, $0 cost) 
 Creates Mission Control tasks for ACTION-worthy emails 
 Auto-archives INFO and SPAM emails 
 Downloads attachments for CEO-forwarded emails 
 Logs all activity to HiveMind and JSONL results 
 

 Accounts Monitored 
 
 
 
 Account Key 
 Email Address 
 Bitwarden Vault Name 
 
 
 
 john john@basicconsulting.no Email - john@basicconsulting.no 
 info info@basicconsulting.no Email - info@basicconsulting.no 
 alai john@alai.no Email - john@alai.no 
 alem alem@alai.no Email - alem@alai.no 
 dev dev@alai.no Email - dev@alai.no 
 gmail alembasic@gmail.com Email - alembasic@gmail.com 
 
 

 Classification Pipeline 
 
 VIP Bypass: Emails from CEO/family → forced to ACTION/high , label: CEO FORWARD 
 Quick Filter: Pattern-based detection for OWN emails and known SPAM 
 Ollama Classification: Remaining emails sent to local llama3.1:8b model 
 Circuit Breaker: Falls back to pattern heuristics if Ollama is down (3 failure threshold) 
 

 VIP Senders (CEO Bypass List) 
 Emails from these addresses bypass all filters and are always classified as ACTION/high with label CEO FORWARD : 
 
 alem@alai.no 
 alem@basicconsulting.no 
 alem.basic@gmail.com 
 alembasic@gmail.com 
 sibilabasic@gmail.com (CEO's wife) 
 riadbasic007@gmail.com (CEO's brother) 
 

 Transport: Himalaya Adapter 
 The daemon uses ~/system/tools/himalaya-adapter.js , which wraps the Rust-based himalaya CLI ( /opt/homebrew/bin/himalaya ). 
 Config: ~/.config/himalaya/config.toml — all 6 accounts configured. 

 

 2. Credentials 

 Bitwarden Storage 
 All email accounts are stored in Bitwarden with vault item names following the pattern: Email - <address> . 

 Gmail Account (Special Configuration) 
 The Gmail account ( alembasic@gmail.com ) uses App Password authentication (not the regular Google account password). 

 Bitwarden Item: Email - alembasic@gmail.com 
 Custom Fields in Vault: 
 
 imap_host = imap.gmail.com 
 imap_port = 993 
 password = App Password (16-character token from Google) 
 

 Himalaya Config 
 File: ~/.config/himalaya/config.toml 
 Contains 6 account blocks with IMAP/SMTP settings. Credentials are loaded from Bitwarden at runtime via mail-native.js . 

 

 3. How to Verify 

 Is the Daemon Running? 
 launchctl list | grep email-agent
# Expected output: PID + exit status 0
# Example: 12345 0 com.john.email-agent
 

 Last Heartbeat (Should Be < 10 Minutes Ago) 
 cat ~/system/logs/email-agent-heartbeat.txt
# Shows timestamp of last successful run
 

 Recent Activity Log 
 tail -20 ~/system/logs/email-agent-launchd.log
# Should show recent classification activity like:
# {"timestamp":"2026-04-15T13:49:06.450Z","service":"email-agent","level":"info","message":"Classifying via Ollama: ..."}
 

 Pending Emails (Email Inbox Tool) 
 node ~/system/tools/email-inbox.js pending
# Lists emails waiting for classification or action
 

 Daemon Status (Full Details) 
 launchctl print gui/$(id -u)/com.john.email-agent
# Shows full launchd status, last run time, exit codes
 

 

 4. Troubleshooting 

 Problem: Daemon Dead (MODULE_NOT_FOUND Error) 

 Symptom: 
 tail -20 ~/system/logs/email-agent-launchd-error.log
# Shows: Error: Cannot find module '~/system/tools/himalaya-adapter'
 

 Root Cause: The himalaya-adapter.js file was accidentally archived or deleted. 

 Fix: 
 
 Verify the file exists: ls -lh ~/system/tools/himalaya-adapter.js 
 If missing, restore from ~/system/tools/archive/ or Git history 
 Restart the daemon:
 launchctl unload ~/Library/LaunchAgents/com.john.email-agent.plist
launchctl load ~/Library/LaunchAgents/com.john.email-agent.plist
 
 
 Verify restart: launchctl list | grep email-agent 
 

 

 Problem: Gmail "Unknown Account" Error 

 Symptom: 
 Error: Unknown account: gmail. Available: john, info, alai, alem, dev
 

 Root Cause: The gmail key is missing from the VAULT_NAMES object in ~/system/tools/mail-native.js . 

 Fix: 
 
 Open ~/system/tools/mail-native.js 
 Locate the VAULT_NAMES object (around line 20) 
 Add the gmail entry:
 const VAULT_NAMES = {
 john: 'Email - john@basicconsulting.no',
 info: 'Email - info@basicconsulting.no',
 alai: 'Email - john@alai.no',
 alem: 'Email - alem@alai.no',
 dev: 'Email - dev@alai.no',
 gmail: 'Email - alembasic@gmail.com' // Add this line
};
 
 
 Save and reload daemon 
 

 

 Problem: Gmail Hanging Daemon (High CPU/Memory) 

 Symptom: 
 
 Multiple overlapping email-agent processes running 
 400%+ CPU usage (seen in top ) 
 Email agent not completing runs 
 

 Root Cause: Gmail IMAP fetch is hanging indefinitely, causing overlapping daemon instances. 

 Fix: 
 
 Identify stuck process:
 ps aux | grep email-agent
 
 
 Kill the stuck process gracefully:
 kill -QUIT <PID>
# Or if unresponsive:
kill -9 <PID>
 
 
 Unload and reload daemon:
 launchctl unload ~/Library/LaunchAgents/com.john.email-agent.plist
launchctl load ~/Library/LaunchAgents/com.john.email-agent.plist
 
 
 

 

 Problem: Vault Credentials Unavailable (Circuit Breaker Triggered) 

 Symptom: 
 Error: Bitwarden session not available
# Or: Circuit breaker OPEN for account: john
 

 Root Cause: Bitwarden CLI session expired or /tmp/bw-session is empty. 

 Fix: 
 
 Check session file:
 cat /tmp/bw-session
# Should contain a session token string
 
 
 If empty, unlock Bitwarden and regenerate session:
 bw unlock --raw > /tmp/bw-session
# Enter master password when prompted
 
 
 Verify session works:
 bw get item "Email - john@basicconsulting.no" --session $(cat /tmp/bw-session)
 
 
 Circuit breaker will reset automatically on next successful run (backoff resets after threshold period) 
 

 

 Problem: Alem's Emails Not Showing as ACTION 

 Symptom: Emails from CEO are classified as INFO or SPAM instead of ACTION/high. 

 Root Cause: VIP_SENDERS list is incomplete or outdated. 

 Fix: 
 
 Open ~/system/daemons/email-agent.js 
 Locate the VIP_SENDERS array (around line 92) 
 Ensure all Alem's addresses are present:
 const VIP_SENDERS = [
 'alem@alai.no',
 'alem@basicconsulting.no',
 'alem.basic@gmail.com',
 'alembasic@gmail.com',
 'sibilabasic@gmail.com',
 'riadbasic007@gmail.com'
];
 
 
 Save and reload daemon 
 

 

 Problem: Ollama Circuit Breaker Open (Fallback Mode) 

 Symptom: 
 WARN: Ollama circuit breaker OPEN — using pattern heuristic
 

 Root Cause: Ollama service is down or unresponsive (3+ consecutive failures). 

 Fix: 
 
 Check Ollama service:
 curl http://localhost:11434/api/tags
# Should return JSON list of models
 
 
 If unresponsive, restart Ollama:
 brew services restart ollama
# Or manually:
ollama serve
 
 
 Circuit breaker will auto-reset after backoff period (starts at 10s, max 5 minutes) 
 Emails will still be processed using pattern-based heuristics during circuit breaker OPEN state 
 

 

 5. Gmail App Password Setup 

 If the Gmail App Password needs to be regenerated (e.g., after credential rotation or security incident): 

 
 Go to https://myaccount.google.com/apppasswords (must be logged in as alembasic@gmail.com) 
 Click Generate 
 Select app: Mail 
 Select device: Mac (or custom name like "IMAP Daemon") 
 Copy the 16-character App Password (no spaces) 
 Update Bitwarden:
 bw get item "Email - alembasic@gmail.com" --session $(cat /tmp/bw-session) | \
 jq '.login.password = "<NEW_APP_PASSWORD>"' | \
 bw encode | \
 bw edit item $(bw get item "Email - alembasic@gmail.com" --session $(cat /tmp/bw-session) | jq -r .id) --session $(cat /tmp/bw-session)
 
Or update manually via Bitwarden web vault.
 
 Reload daemon:
 launchctl unload ~/Library/LaunchAgents/com.john.email-agent.plist
launchctl load ~/Library/LaunchAgents/com.john.email-agent.plist
 
 
 

 

 6. Key Files and Locations 

 
 
 
 File 
 Purpose 
 
 
 
 ~/system/daemons/email-agent.js Main daemon script 
 ~/system/tools/mail-native.js VAULT_NAMES map + credential loader 
 ~/system/tools/himalaya-adapter.js Himalaya CLI wrapper (IMAP/SMTP) 
 ~/.config/himalaya/config.toml Himalaya account configuration 
 ~/Library/LaunchAgents/com.john.email-agent.plist LaunchAgent config (5-minute interval) 
 ~/system/logs/email-agent-launchd.log Daemon stdout log 
 ~/system/logs/email-agent-launchd-error.log Daemon stderr log 
 ~/system/logs/email-agent-heartbeat.txt Last successful run timestamp 
 ~/system/logs/email-triage-results.jsonl JSONL log of all classifications 
 /tmp/bw-session Bitwarden CLI session token 
 
 

 

 7. Escalation 

 If the daemon is down for > 30 minutes and troubleshooting steps do not resolve: 

 
 Check email-agent-launchd-error.log for stack traces 
 Capture full logs:
 tail -100 ~/system/logs/email-agent-launchd.log > /tmp/email-agent-debug.log
tail -100 ~/system/logs/email-agent-launchd-error.log >> /tmp/email-agent-debug.log
launchctl print gui/$(id -u)/com.john.email-agent >> /tmp/email-agent-debug.log
 
 
 Slack alert to #ops :
 node ~/system/tools/slack.js send ops "@john Email Agent daemon DOWN for 30+ minutes. Logs: /tmp/email-agent-debug.log"
 
 
 Fallback: manually check inboxes via webmail until daemon is restored 
 

 

 Document Status: ✅ Production 
 Owner: John (primary agent) 
 Last Incident: 2026-02-25 — MODULE_NOT_FOUND (himalaya-adapter archived) 
 Last Review: 2026-04-15