Skip to content

feat(email): health and cost view, reply check, retention purge, setup docs (EA-8) - #642

Open
privatejoel wants to merge 1 commit into
claude/email-ea7-uifrom
claude/email-ea8-ops
Open

privatejoel wants to merge 1 commit into
claude/email-ea7-uifrom
claude/email-ea8-ops

Conversation

@privatejoel

Copy link
Copy Markdown
Collaborator

Summary

EA-8 is the last PR of the email accountability plan (#634, phase 6). It adds operations and the deliverables document.

Stacked on #641 (EA-7) ← #640 ← #639 ← #638 ← #637 ← #636 ← #635 ← #619.

  • GET /api/email/health (email.rules, admin) returns the module's health and cost for the tenant:

    • mailbox totals: active, paused, need a sign-in, disconnected;
    • the requests today against the summed budget, quota errors and checkpoint resets;
    • the scheduler heartbeats (email/sync, email/sweep, email/sweep_daily, email/purge, cron/tick, cron/daily);
    • the evidence that waits for a person, the failed notices, and the actions by state;
    • what observe mode would make or verify;
    • the effective policy.

    It returns safe columns only, with no token and no checkpoint. A card on Email Actions > Mailboxes shows it to admins.

  • POST /api/email/check { id } is the onboarding check for known limit 1. The owner or an admin can run it.

    • It reads the newest 10 sent messages: 1 request on Outlook, or 1 + 10 on Gmail. These requests count against the mailbox budget.
    • It reports whether the replies carry In-Reply-To or References, and on Outlook whether they carry a step in conversationIndex.
    • The verdicts are headers_ok, index_only, headers_missing and no_replies_in_sample, each with a plain sentence.
    • It is read only and audited. A mailbox that needs a sign-in gets 409. A spent budget gets 429, with no request.
    • Each mailbox row in the UI has a check replies button.
  • email/purge runs daily as a new cron/daily entry with a 30-hour heartbeat bound. It clears preview on actions older than email_content_retention_days (default 30) and stamps content_purged_at. The subject, the IDs and the reasons stay. Anvil never stores a body or an attachment.

  • docs/EMAIL_ACCOUNTABILITY_SETUP.md holds the final deliverables of the request:

    • the architecture summary, the files and modules, and the migrations with their apply order;
    • the exact Outlook and Google registration steps and permissions;
    • the environment variables (none new), and the dependencies (existing and new: no new runtime package);
    • the explicit cost statement: no paid API, no paid service, no new mandatory recurring cost, no LLM;
    • the quota and cost safeguards, the deployment and mailbox onboarding steps, the known limits;
    • the acceptance checklist, which maps the 18 required tests to test files.
  • docs/CRONS.md lists the four email handlers.

Deploy notes

  1. Merge the stack below this PR first. No new migration.
  2. The new email/purge daily entry needs no setting. It runs only for tenants with the module on.
  3. Follow section 9 of docs/EMAIL_ACCOUNTABILITY_SETUP.md to onboard a customer. Run check replies on each mailbox before you switch the tenant to create.

Tests

src/v3-app/api-email-ops.test.js (12 tests):

  • Reply-header report:
    • Headers on every reply give headers_ok. Headers on only some replies are not ok.
    • On Outlook, an index step on every reply gives index_only, and a root index is not a step.
    • Gmail never counts an index (with_index 0).
    • A sample with no reply says so.
  • Check endpoint:
    • Outlook: it reads the newest sent items once, with the MAPI properties. The request counts against the budget, and the check is audited.
    • Gmail: it lists SENT and reads each message as metadata. Two requests are counted.
    • Another user's mailbox is 404. A mailbox that needs a sign-in is 409. A spent budget is 429, and no request is made.
  • Health:
    • Only email.rules can read it.
    • The test checks the totals, the evidence that waits (this tenant only), the failed notices, the states (email items only), the schedulers (email workers only) and the policy.
    • The response has no token column.
  • Purge:
    • Only the preview of an old action is cleared, and the subject stays. Newer rows, rows already purged and other tenants are untouched.
    • A tenant's own retention applies.
    • The cron endpoint needs the secret.
  • [17] End to end:
    • A mailbox with a budget of 3 makes exactly 3 requests in the first run (the page cap).
    • The next run has no budget left: it makes no request, pauses the mailbox until 00:00 UTC, and sends one admin alert.
    • A third run makes no request and sends no second alert.
    • The health view then shows the mailbox paused, with 3 of 3 requests used.

screens/email-actions.test.tsx adds 1 test (13 in total): check replies shows the verdict, and the health card is for an admin only.

The whole module: 12 test files, 212 tests, all pass.

Mutation check: I broke each rule, ran the files and restored the code. All 13 mutations failed the tests:

  • the check not counted against the budget; the check on another user's mailbox; the check ignores the budget;
  • the health view open to any writer; the health view returns token columns; the health view counts another tenant's evidence;
  • the purge crosses tenants; the purge stamps purged rows again; the purge clears the subject; the tenant retention ignored;
  • Gmail counts an index; some headers count as ok;
  • the health card shown for every role.

One of these mutations ("Gmail counts an index") first survived. I made its test stronger.

Gates:

  • npm run check: pass.
  • npm run lint: 0 errors. The new files add no warnings.
  • npm run build: pass.
  • npm run verify: pass. I restored the unrelated rewrites of the audit docs.
  • npm run eval:golden: pass.
  • NODE_OPTIONS=--no-experimental-webstorage npx vitest run: 640 files, 7,689 tests, all pass.

Not covered

  • The providers are not tested with a live mailbox. The check endpoint is the tool for that. Its result on a real Outlook and a real Gmail mailbox is still to be seen.
  • No editor for the policy in the UI. The health card shows the effective policy, and PUT /api/email/policy sets it.
  • shortcut: the health counts read at most 10,000 rows. Switch to count queries when a tenant passes that.
  • The purge clears 500 actions per tenant per day. A large backlog takes more days, and the response says more: true.

🤖 Generated with Claude Code

…p docs (EA-8)

GET /api/email/health (email.rules): mailbox totals against the budget,
schedulers, evidence waiting for a person, failed notices, actions by
state, observe-mode counts and the effective policy. POST
/api/email/check: the onboarding check reads the newest sent messages and
reports whether replies carry In-Reply-To/References or an Outlook index
step. The daily email/purge clears previews past the tenant's retention.
docs/EMAIL_ACCOUNTABILITY_SETUP.md: architecture, files, migrations,
provider setup, env vars, dependencies and cost, safeguards, onboarding,
known limits and the acceptance checklist.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@vercel

vercel Bot commented Oct 26, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
anvil Ready Ready Preview Oct 26, 2026 2:52am UTC

This branch was successfully deployed

1 active deployment
Preview — bedb9f27 Deployed Oct 26, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant