diff --git a/docs/phase7-summary-hub.md b/docs/phase7-summary-hub.md new file mode 100644 index 0000000..508f04e --- /dev/null +++ b/docs/phase7-summary-hub.md @@ -0,0 +1,251 @@ +# Phase 7 — Summary and Hub + +Status: **built, tested, deployed on `.13`, and the project side of the DoD is +demonstrated against real mail.** Two items wait on Sam's explicit approval: the +real summary email (Apprise key) and registering this project with the running +Hub. Parent [AUD-68](/AUD/issues/AUD-68). Phase 7 of AGENTS.md §11. Code commit +`a349b42`. + +**DoD:** the Hub asks "anything important in my inbox?" and gets a correct short +answer. — the Hub contract round-trip works (§2.1). Wiring the live Hub requires +a shared token and a Hub restart, which is outside the "do not touch other +projects" rule for this pass (see §7). + +## 1. What was built + +### 1.1 Hub API (FR-12) + +The project side of the frozen contract +(`central_ai_llm_master/docs/ask-contract.md`) lives in `internal/hub` and +`internal/server/hub.go`. + +| Endpoint | Auth | Behaviour | +|---|---|---| +| `GET /capabilities` | `Authorization: Bearer $HUB_TOKEN` | `{"project":"email_agent","topics":["email","inbox","mail","message"],"people":["sam"]}` | +| `POST /ask` | `Authorization: Bearer $HUB_TOKEN` | A short, speakable answer or `{"answer":null,"reason":…}` | + +- **Read-only.** `/ask` calls only `store.CountByCategory` and + `store.MessagesByCategory`. It never writes, including no `actions_log` row + (FR-13 is for actions, not reads). Proven live in §2.3 and by the unit test + `TestAskWritesNothing`. +- **No LLM, fast.** The answerer is deterministic and answers from SQLite in + milliseconds. The 3-second contract budget is never at risk. +- **Never guesses.** An unanswerable question returns `answer: null` plus a + reason. The service does not track read/unread, so it says so rather than + inventing a number. +- **Token required.** With no `HUB_TOKEN` configured the endpoints return `503`; + a wrong token returns `401`. No project trusts an unsigned request. +- Topics deliberately omit `unread` (see `routing.md`), because the service has + no read-state store. + +Intents answered: **important / urgent / action**, **spam**, **newsletter / +unsubscribe**, **inbox count**, and a one-sentence **overview / summary**. + +### 1.2 Outbound notify (ask-contract "Notify (project to Hub)") + +`internal/hub/notify.go` posts to `{HUB_BASE_URL}/notify` with +`{"from","level","message","person"}` and the project bearer token. It is the +one Hub call this service makes. The Hub's `/notify` receiver is not part of its +frozen v1 routes (`docs/hub-api.md` §12), so the call is best-effort and a +failure is logged, never blocking local work. The CLI `-notify` exercises it. + +### 1.3 Daily summary (FR-10) + +- `internal/summary` builds a deterministic plain-text summary: inbox total, + per-category counts, the "needs attention" list, newsletter count, and spam + count (with the "recommend, never auto-delete" wording from AGENTS.md §10.5). +- `internal/store/summary.go` adds `CountByCategory`, `MessagesByCategory`, and + summary CRUD over the existing `summaries` table. **No schema migration** was + needed; the table exists since v1. +- `internal/apprise` delivers the summary by email through the house Apprise API + (`POST {APPRISE_URL}/notify/{APPRISE_KEY}`, or the stateless `/notify` form + with `APPRISE_URLS`). Set `APPRISE_TOKEN` if the API is protected. +- Delivery happens in exactly two explicit paths: the CLI `-summary-send` (for + the daily n8n schedule) and the Reports screen's **Send now** button. Building + a summary never sends mail. +- `GET /reports` is the Reports screen (AGENTS.md §5): build today's summary, + send it, and delete a stored report. All mutations are CSRF-protected POSTs. + +### 1.4 CLI + +| Flag | Effect | +|---|---| +| `-summary` | Build today's summary, store it, print it. Sends nothing. | +| `-summary-send` | Build, store, and deliver by email via Apprise. | +| `-notify` | Send one notification to the Hub (`POST /notify`). | + +The n8n schedule (FR-1) runs `-summary-send` once a day; the summary job is a +separate bounded process, like `-fetch` and `-classify`. + +## 2. DoD evidence + +### 2.1 Real `/ask` round-trip + +Against the deployed container on `.13` (commit `a349b42`), sending the exact +`ProjectClient` request shape the Hub uses (`content-type: application/json`, +`Authorization: Bearer …`): + +``` +POST /ask +{"question":"anything important in my inbox?","asker":"sam"} + +200 {"answer":"20 emails need your attention, including \"Security alert\" from Google.", + "data":{"count":20,"messages":[ … ]},"expires":"2026-10-11T11:48:01Z"} +``` + +The count is correct: the live inbox held **102** messages, of which **19 Action ++ 1 Important = 20** needed attention. An overview question returns +`"Your inbox has 102 emails: 20 need attention and 40 are newsletters."` + +`GET /capabilities`: + +``` +{"project":"email_agent","topics":["email","inbox","mail","message"],"people":["sam"]} +``` + +Auth checks: no token → `401`; wrong token → `401`; correct token → `200`. +An unanswerable question returns `{"answer":null,"reason":"I do not track read +or unread mail"}`. + +### 2.2 `/notify` path + +`email-agent -notify` against a local stub implementing the contract captured: + +```json +{ + "path": "/notify", + "auth": "Bearer ", + "body": { + "from": "email_agent", + "level": "info", + "message": "Email Agent notify path check.", + "person": "sam" + } +} +``` + +This matches the `NotifyRequest` shape in `ask-contract.md` exactly. + +### 2.3 `/ask` is read-only + +Five `/ask` calls (important, count, spam, unknown, overview) were issued against +the deployed service. The `/data` SQLite database was copied before and after and +compared row-by-row: + +| table | before | after | delta | +|---|---|---|---| +| messages | 103 | 103 | +0 | +| classifications | 403 | 403 | +0 | +| actions_log | 428 | 428 | +0 | +| summaries | 0 | 0 | +0 | +| rules | 2 | 2 | +0 | +| unsubscribe | 0 | 0 | +0 | +| drafts | 2 | 2 | +0 | + +No table changed. The unit test `TestAskWritesNothing` asserts the same property +for the message, classification, action-log, and summary counts. + +### 2.4 Daily-summary-by-email path + +`docker exec email-agent email-agent -summary` produced and stored the summary +(row `id=1`, date `2026-10-11`, 1110 bytes, `delivered_to` empty): + +``` +Email Agent — daily summary for 2026-10-11 + +Inbox: 102 message(s) + Newsletter 40 + Auto-reply 34 + Action 19 + Info 7 + Important 1 + Spam 1 + +Needs attention: 20 + - Security alert — Google [Action/high] + - … + +Newsletters: 40 +Spam (recommend, never auto-delete): 1 +``` + +`-summary-send` with no Apprise key stops before sending: +`summary failed: apprise is not configured: set APPRISE_URL and APPRISE_KEY (or +APPRISE_URLS)`. **No summary email has been sent.** A real send waits on Sam's +approval and an Apprise key (§7). + +### 2.5 Automated tests + +`gofmt -l` clean, `go vet ./...` clean, `go test ./...` green (in +`golang:1.25-alpine`). New coverage: + +| Package | Tests | +|---|---| +| `internal/hub` | important/empty/spam/newsletter/count/summary/unknown intents, person and asker checks, unread refusal, read errors, sender-name extraction, default capabilities, notify payload/auth/error/no-op | +| `internal/apprise` | key mode, stateless URL mode, auth header, error status, `Configured` | +| `internal/summary` | build counts and ordering, text rendering, empty inbox | +| `internal/store` | category counts, multi-category importance ordering, summary upsert/get/list/delete/delivery | +| `internal/config` | Hub/Apprise defaults, `HubConfigured`, `AppriseConfigured`, URL-list parsing | +| `internal/server` | capabilities auth + shape, ask auth, ask answer, **ask writes nothing**, reports page auth, generate stores without sending, send delivers through Apprise, CSRF | + +## 3. Configuration + +New environment variables (names only; values live in +`~/.config/environment.d/10-secrets.conf` on `.13` and are never committed): + +| Variable | Purpose | +|---|---| +| `HUB_TOKEN` | Shared bearer token for `/capabilities` and `/ask`. Also the token sent to the Hub's `/notify`. | +| `HUB_BASE_URL` | Hub base URL for outbound notify (default `http://192.168.20.13:8788`). | +| `HUB_NOTIFY_TIMEOUT` | Notify call timeout (default `5s`). | +| `APPRISE_URL` | Apprise API base (default `http://192.168.20.35:8210`). | +| `APPRISE_KEY` | Stored Apprise configuration key. | +| `APPRISE_URLS` | Stateless Apprise destinations (used when no key). | +| `APPRISE_TOKEN` | Optional bearer token for a protected Apprise API. | +| `EMAIL_AGENT_SUMMARY_TO` | Summary recipient (default `samuelrolfe@gmail.com`). | + +A `HUB_TOKEN` was generated and written to the secrets file on `.13` (mode 600, +backup `10-secrets.conf.bak.aud73-*`). The value is not in this repo. + +## 4. Deployment + +On `.13`, from the repo, with the host secrets in scope: + +```sh +set -a; . ~/.config/environment.d/10-secrets.conf; set +a +EMAIL_AGENT_VERSION=phase7 EMAIL_AGENT_COMMIT=$(git rev-parse --short HEAD) \ + docker compose build +docker compose up -d +``` + +The migration-free change started in place on the Phase 1–6 volume +(`schema_version: 6`). `https://mail.lab.audasmedia.com.au/health` → `200`. + +## 5. Rollback + +1. `git revert a349b42 && docker compose up -d --build`. +2. No schema change to undo. The `summaries` table rows and the `HUB_TOKEN` + secret are left in place; remove the token from the secrets file if the Hub + API must be disabled. +3. The Reports screen, `/capabilities`, and `/ask` disappear with the revert; + the running Hub is unaffected because it is not yet registered. + +## 6. Not done / deferred + +- **1-month body retention** (§7) is still not implemented. +- The Hub's `/notify` receiver does not exist yet in the Hub v1, so the outbound + path is verified against a stub, not the live Hub. +- The Hub routing decision is LLM-based (`understand.OmniRouter`). This pass did + not run the Hub pipeline, to respect "the Hub endpoints are the only external + calls" — no OmniRoute routing call was made. + +## 7. Waiting on Sam (two approvals) + +1. **Real summary email.** Provide the Apprise key (or URLs) and approve one + real send for evidence. Until then no summary email is sent. +2. **Register this project with the Hub.** Add + `HUB_PROJECT_EMAIL_AGENT_TOKEN=` and + `HUB_PROJECTS=email_agent=http://192.168.20.13:8790` to the Hub's environment + and restart the `hub` container. This touches a running family service, so it + needs Sam's yes. After that the Hub can route "anything important in my + inbox?" through `routing.md` to this project.