Envoy is an email-native AI agent. It monitors an IMAP mailbox, reads incoming emails, and processes each one through a structured, phase-driven reasoning loop. It combines OpenAI LLM calls with a persistent JSONHTL notes system and direct IMAP operations (search, fetch, move, delete).
At its core, Envoy is an orchestrator (orchestrator.py) that coordinates three main systems:• IMAP (via imap_client.py) for reading and modifying email.• An LLM (OpenAI, strict JSON schema) for reasoning and decision-making.• A structured notes store (JSONHTL documents) for persistent memory.
All LLM outputs must conform to a strict EnvoyResponse schema. This guarantees that every iteration returns explicit fields for note writes, email sends, searches, moves, deletes, and a phase status.
On each run, Envoy opens a single IMAP connection and processes all UNSEEN emails in the target folder (default INBOX). For each email, it enters an iteration loop (up to a per-run limit, with a hard total limit across continuations).
Each iteration follows this pattern:1. Load global start notes and the current phase note (envoy/states/{phase}).2. Auto-load any context bundle if bundle_key is set.3. Call the LLM with structured output.4. Immediately dispatch actions such as write_notes, delete_notes, and send_emails.5. If non-terminal, perform requested gathering (notes, email fetches, searches) and loop.6. If terminal (complete or escalate), execute move/delete actions and exit.
If the iteration limit is reached before completion, Envoy sends itself a continuation email containing a JSON attachment with working state (working_note, bundle_key, current_phase, failed_fetches, etc.). On resume, that state is restored and processing continues.
Envoy operates as a finite state machine. The LLM sets a status field each iteration to indicate the current phase.
Non-terminal phases include: triage, gathering, summarising, working, coding, composing, and waiting. These continue the loop and allow incremental progress.Terminal phases are: complete (task finished, apply final email moves/deletes) and escalate (cannot proceed without human intervention).
In Phase Design v2, each phase owns its model tier (nano/mini/full), and the orchestrator switches models automatically on phase transition. An idle counter prevents infinite loops by progressively discouraging remaining in the same phase and eventually forcing a transition if no progress is made.
Together, the structured schema, phase-aware state machine, strict action dispatch, and continuation mechanism make Envoy a deterministic, inspectable, and recoverable email-native AI agent rather than a single-shot chatbot.