A specialized email agent configured to receive emails at envoy@critchley.biz for intelligent autonomous operations and decision-making support.
• Design Specification — Architecture, mailbox design, memory model, and agent behaviour
• Design Decisions Supplement — Finalised decisions on mail transport, control plane, iterative processing, and safety
• Folder System Design — IMAP folder organization architecture, automatic creation, bootstrap discovery
• Phase-Aware Processing Design — State machine, RAG principle, context bundles, summarisation, per-state instruction notes
• Orchestrator Implementation — Processing loop, IMAP architecture, phase-aware FSM, continuation emails, command line options
• IMAP Client Module — Simple IMAP interface using imaplib and .netrc credentials
• Code Overview — File map, phase-aware schema, processing flow, action dispatch, context bundles
• Agent Bootstrap Instructions — Core instructions loaded into LLM context on every run
Per-state instruction notes, auto-loaded by the orchestrator before each LLM call. Advisory — Envoy can update these.
• envoy/states/triage — First pass: read email, understand sender and intent, decide approach
• envoy/states/gathering — Load context: fetch notes, search emails, retrieve reference material
• envoy/states/summarising — Condense large docs into scratch/ notes, drop originals from context
• envoy/states/working — General processing: analysis, research, writing
• envoy/states/coding — Code-writing: load existing code first, one routine per iteration
• envoy/states/composing — Prepare outbound emails; primary email-sending phase
• envoy/states/waiting — Park until reply: dispatches send_emails immediately, sends continuation, stops run
• Continuation Emails — Pause/resume across cron runs via MIME email with JSON state attachment (bundle_key, current_phase, failed_fetches)
• Mail Delivery Loop — End-to-end chain: external MX → Outlook → popit3 → WebDAV → noodle IMAP → orchestrator; cron schedule
• Testing Guide — Test harness (test_orchestrator.py), scenarios, bugs found and fixed, known limitations
• Email Address Rewriting — Outbound address cleaning and mapping (e.g. bluewin.ch → critchley.biz)
• Email Access Guide — Two-stage search/fetch pattern, search_flags, headers-only search, multiple searches per iteration
• Logging System — Enhanced action logging and debug commands
• Email Organization Guide — Folder structure, disposition guidelines, search strategies
• Usage Guide — Best practices for asking Envoy questions
• 2026-02-22 — Phase-aware state machine, dispatch_immediate_actions, context bundles, bug fixes, test harness
• 2026-02-13 — Continuation emails, multi-mailbox, single IMAP connection, expunge on startup
• 2026-02-12 — Initial implementation, schema/move bugs fixed, flags search feature
• TODO List — Planned features and improvements
• Issues — Known issues and their status
• Case Studies — real task failures analysed for root causes and recommendations
• Improvements — concrete code and notes changes derived from case studies
• Email Address: envoy@critchley.biz• IMAP Host: imap (credentials in ~/.netrc)• Start Note: envoy/start• Model Tiers: gpt-4.1-nano / gpt-4.1-mini / gpt-5.2-chat-latest• Repository: ~/py/envoy/ (git)
Integrated into PopIt3 email processing pipeline. See Mail Delivery Loop for the full chain.
Phase-aware processing fully operational as of 2026-02-22. 9-state FSM: triage → gathering → summarising → working → coding → composing → waiting (non-terminal) + complete + escalate (terminal). All non-terminal phases dispatch send_emails/write_notes/delete_notes immediately via dispatch_immediate_actions(). Context bundles (bundle_key) auto-load related notes per thread. Per-state instruction notes auto-loaded before each LLM call.