feat(email): scheduled send + snooze (one-shot scheduler, cancel handles)

[kovtcharov]

"Send this tomorrow at 9am" and "snooze this until Monday" simply didn't exist in the email agent — both are table-stakes in every comparable mail client, and neither Gmail nor Outlook exposes them via API (they're client-side features), so users had no workaround. This adds both as agent tools on a new persistent one-shot scheduler: a scheduled send is user-confirmed at creation (literal recipient/subject/body + fire time, per the #1264 Tier-2 gate) and then fires unattended at/after its time; snooze drops the message out of INBOX now and brings it back at the chosen time. Both are cancellable until they fire, jobs survive restarts (past-due jobs fire on next start), and a firing failure is recorded on the job and logged — never silently swallowed.

Since PR #1371 (gaia schedule cron dispatch) is approved but unmerged, the scheduler is deliberately minimal and email-scoped, with a documented seam: once #1371 lands (autonomy epic #555), its dispatcher can drive fire_due_jobs() directly — no store or tool changes. Privacy note: the pending send lives as a regular draft in the user's mailbox; the body is never persisted in the agent's SQLite.

Closes #1609

Test plan

• python -m pytest hub/agents/python/email/tests/test_email_schedule.py -v — 16 tests covering the issue's acceptance criteria: fires once at/after its time and not before; snoozed message leaves INBOX and re-surfaces on time; cancel prevents both; send failure at fire time is persisted + loud; snooze rolls back the archive if the job write fails; jobs persist across restart; a scheduled send fired from the real polling thread writes its audit row safely (cross-thread sqlite regression guard).
• python -m pytest tests/unit/agents/test_email_agent.py tests/unit/agents/test_email_agent_confirmation.py tests/integration/test_never_auto_send.py — confirmation gating: schedule_send is in TOOLS_REQUIRING_CONFIRMATION; the never-auto-send invariant is unchanged.
• python util/lint.py --all — clean.
• Manual (needs a connected mailbox): gaia email, ask "send X to Y tomorrow at 9am" → confirmation shows literal payload + time; list_scheduled_jobs shows the job; cancel_scheduled_job cancels it; draft is visible in the mail client.

[github-actions]

Verdict: Approve — no blocking issues.

This adds scheduled-send and snooze to the email agent via a new persistent one-shot job scheduler: a scheduled send is confirmed at creation (literal recipient/subject/body + fire time), the body stays as a mailbox draft rather than in SQLite, jobs survive restarts and fire on the next start if their time already passed, and firing failures are recorded on the job and logged rather than swallowed. The design is careful in the places that matter — the "backend call first, job row only on success" ordering, the atomic pending → firing claim that guarantees exactly-once firing, the snooze archive-rollback when the job write fails, and a dedicated per-pass DB connection so the polling thread never shares the agent's sqlite handle. Test coverage is genuinely thorough (16 tests hitting each acceptance criterion plus a cross-thread regression guard), and all four npm doc surfaces (README/SPEC/SKILL/CHANGELOG) plus the guide were updated together.

Only a few minor notes below, none blocking.

🔍 Technical details

🟢 Minor

Polling thread has no explicit stop hook (agent.py:349-358) — start_scheduler=True spins up a daemon thread but there's no stop()/close on the agent, so it's only reclaimed at process exit. That's correct for the long-lived REST sidecar (one agent per process), and tests disable it. It would only leak a thread if an EmailTriageAgent were constructed-and-discarded inside a long-lived process. Worth a small stop()/__del__ hook if that ever becomes a usage pattern — fine to leave as-is for now.

Concurrent-writer busy timeout is implicit (scheduler.py) — the polling thread's per-pass connection and the agent's main-thread connection both write email_scheduled_jobs on the same file. The atomic claim is correct (SQLite serializes writers), but collisions rely on sqlite3's default 5s busy timeout — there's no explicit busy_timeout/WAL. Very low risk at a 30s poll with tiny writes; noting it in case poll intervals ever shrink.

mark_failed sets fired_at (schedule_store.py:452-458) — a job that failed to fire gets a fired_at timestamp. Cosmetic only (the error column and failed status carry the real signal), but the column name reads as "this fired," which it didn't.

Strengths

• Fail-loud throughout, matching the repo rule: missing executor → job marked failed with a persisted reason; executor exception → failed + log.exception; snooze rollback raises a message that names the exact mailbox state ("archived with no scheduled return") instead of leaving the message silently vanished.
• The cross-thread sqlite trap is both avoided and tested — _execute_scheduled_send writes its audit row through the scheduler's per-pass connection, and test_polling_thread_fires_scheduled_send_with_db_write is a real regression guard for it rather than a happy-path smoke test.
• Correct scope discipline: schedule_send is added to TOOLS_REQUIRING_CONFIRMATION (Tier-2 at creation, feat(email): send with confirmation (never auto-send) #1264) while snooze stays ungated as a reversible organize-tier action, and the "no REST route yet" boundary is documented consistently across README/SPEC/SKILL so integrators don't look for a client.scheduleSend() that doesn't exist.

[itomek]

Branch updated to main and the scheduler verified working on real hardware with real wall-clock timing — this PR is ready to merge.

Real-world proof — Ryzen AI box (Radeon, Ubuntu), Lemonade v10.8.1 + Gemma-4-E4B, real EmailJobScheduler polling thread (no injected clocks):

Step	Result
schedule_send ~75s out (planted subject/body)	Job persisted pending; body kept out of the SQLite payload (privacy invariant held)
Real fire	fired_at − due_at = +1.027s — at/after due, never early; draft sent once
One-shot	3 further poll passes: send count still 1, row status=fired (consumed)
Cancel handle	Second job flipped to cancelled; double-cancel rejected loudly (no silent no-op)
Snooze 30s	Message left INBOX, resurfaced at +1.040s after due with prior labels restored
LLM-in-the-loop	Live Gemma chose schedule_send with correct args; the new confirmation gate fired (15.1s end-to-end)

Notes

• Only red check ("API Tests") is pre-existing on main — identical email-route 404 signature on main's latest run (50c17de). behavior-e2e is green after the update.
• Merge to main: 2 conflicts (CHANGELOG + system-prompt block vs the merged voice tools), both sides kept. src/gaia/agents/base/agent.py change is a single addition of schedule_send to TOOLS_REQUIRING_CONFIRMATION — no prompt-assembly or parsing paths touched.
• Local suite: 16/16 new schedule tests; 1311 passed across email suites; full tests/unit/ failures (8) all reproduce identically on main (pre-existing). Lint fully green.
• Minor observation, non-blocking: the scheduler logs "Database initialized" at INFO on every poll pass (~2,880 lines/day at the 30s default) — worth downgrading to DEBUG or logging once in a follow-up.

[itomek]

Final status: fully green and mergeable at dc05e4f — conflicts from the #1917/#1921 merges resolved, all checks passing (the API Tests fix from #1939 is now on main), 822 tests + lint green locally. Real-world scheduler evidence is in the comment above; the spec's capability-17 row was also corrected to Wired in this update.