# Email Triage Agent

Deterministic email triage for Hermes Agent. It classifies messages into P0–P3 or `REVIEW`, emits the shared `pif.event.v1` contract, and lets Hermes deliver the result through its existing Feishu gateway.

确定性的 Hermes 邮件分诊 MCP：不确定就保留，V1 永不删除、永不发信，飞书凭证继续由 Hermes 管理。

## Why / 设计理念

- Reduce information, do not create more of it.
- `P0` is immediate; `P1` waits for a digest; `P2/P3` are audit-only.
- Sender-auth conflicts and low confidence become `REVIEW/HOLD`.
- Human feedback updates an external JSONL rule trail, never model weights.
- The optional adapter connects through read-only IMAP or the Gmail API with `gmail.readonly`. It never executes Delete, Send, Move, Label, Archive, or Seen changes.

## Local run

```bash
npm ci
npm test
npm run demo
```

Real mailbox adapter commands:

```bash
node src/adapter-cli.js authorize-gmail --account gmail-main
node src/adapter-cli.js test --account gmail-main
node src/adapter-cli.js poll --accounts gmail-main,gmail-second
```

Credentials are references to macOS Keychain items or environment variables; literal passwords and tokens are rejected by config validation. For persistent personal Gmail access, publish the Google OAuth audience as **In production** before authorizing accounts; do not leave the deployment in Testing. See the [read-only mailbox adapter guide](docs/EMAIL_ADAPTER.md) and the [multi-account Gmail OAuth guide](docs/GMAIL_OAUTH.md).

One-off classification:

```bash
node src/cli.js --json '{"sender":"no-reply@accounts.google.com","subject":"New login detected","auth":{"spf":"pass","dkim":"pass","dmarc":"pass"},"protectedSender":true}'
```

## Add to Hermes on macOS

Hermes discovers stdio MCP tools from `~/.hermes/config.yaml`. Clone and install, then use an absolute path:

```bash
git clone https://github.com/roclee2692/email-triage-agent.git ~/Projects/email-triage-agent
cd ~/Projects/email-triage-agent && npm ci
hermes mcp add email-firewall --command node --args "$HOME/Projects/email-triage-agent/src/mcp.js"
hermes mcp test email-firewall
```

Hermes registers tools with names such as `mcp_email_firewall_triage_email`. The server never needs Feishu secrets: Hermes already owns the Feishu channel and presents or schedules the returned message.

## Tools

- `triage_email`
- `render_feishu_email`
- `record_email_feedback`
- `get_email_policy`
- `authorize_gmail_account`
- `poll_email_accounts`
- `test_email_account`
- `acknowledge_email_events`

The companion repository is [`crypto-market-sentinel`](https://github.com/roclee2692/crypto-market-sentinel). Both return the same event envelope, so one Hermes prompt can apply the same urgent/digest/audit policy.

See [Hermes macOS setup](docs/HERMES_SETUP.md) and the shared [PIF event contract](docs/PIF_EVENT_V1.md).

## License

MIT. See [LICENSE](LICENSE).