@aitne-sh/aitne 0.1.0

package/agent-assets/skills/mail/SKILL.md

@@ -0,0 +1,313 @@
+---
+name: mail
+description: Load when reading, searching, sending, drafting, replying, tagging, or filing email — Gmail, Outlook, Yahoo, and iCloud accounts share one route surface, with provider-native translation at the daemon.
+allowed-tools:
+  - Bash(curl *)
+  - Read
+---
+
+# Mail Operations Guide (multi-provider)
+
+All mail work goes through `/api/mail/*`. Gmail, Outlook, Yahoo, iCloud —
+same route surface, per-account routing, provider-native translation at the
+daemon.
+
+## 0. Delegation-aware routing (read before §1)
+
+This body is materialized only in direct mode and same-backend Gmail
+delegation. (Cross-backend Gmail delegation pulls
+`SKILL.delegated.<backend>.md` instead — that variant has its own
+routing prose.) Read the `<integration_modes>` block injected above:
+
+- **Non-Gmail accounts (iCloud, Outlook, Yahoo, IMAP):** unaffected —
+  use the `/api/mail/:acct/*` endpoints documented below regardless of
+  Gmail's mode.
+- **Gmail accounts AND `gmail="delegated"` (same-backend):** the
+  per-account gate inside the mail handler returns
+  `410 {"error": "integration_delegated"}`. Do NOT retry through
+  `/api/mail/*`. Use the connector tools your session already holds
+  natively — `mcp__claude_ai_Gmail__*` (Claude session),
+  `mcp__codex_apps__gmail._*` (Codex session), or
+  `mcp_google-workspace_gmail.*` (Gemini session, via the
+  `google-workspace` extension).
+
+Account-resolution (§1) is unchanged: `accounts.md` lists every active
+account regardless of mode. The branch above only affects the wire call
+once an account is selected.
+
+## 1. Account resolution (do this first)
+
+`accounts.md` (next to this file) lists the active accounts available this
+session — scope-gated to `enabled provider ∧ account.active ∧ healthy`. If
+the file is absent or empty, there are no active mail accounts: tell the
+user and stop. Account setup is outside this skill's scope — do NOT
+speculate about how to add one.
+
+There is **no global "primary" account**. Pick one from conversation
+context, in this order:
+
+1. **User named it.** `"email from my work gmail"` / `"reply from my
+   icloud"` → match against the `email` / `label` columns in `accounts.md`.
+2. **Replying to a thread.** The reply MUST go from the account that
+   received the original. Find it by the `accountId` attached to the
+   message/thread you fetched.
+3. **Exactly one active account.** No ambiguity — use it.
+4. **Multiple active, no context clue.** Ask the user which account to
+   use. Do NOT pick arbitrarily.
+
+If an API call returns `404 not_found` on an id you resolved from
+`accounts.md`, the file may be stale. Re-fetch the scope-gated set:
+
+```bash
+curl -s "http://localhost:8321/api/mail/accounts?active=1"
+```
+
+This returns the same filtered view `accounts.md` was materialized from.
+Do NOT call `GET /api/mail/accounts` without `?active=1` for recovery — it
+includes dormant and unhealthy rows that every operation will reject.
+
+## 2. Decision rules
+
+### Send vs draft
+- **Prefer drafts.** Create via `POST /mail/:acct/drafts`. The user sends
+  from the provider's web UI.
+- Direct send (`POST /mail/:acct/messages/send`) succeeds autonomously —
+  the daemon does not DM the owner before sending. (The user's
+  `deniedTools` list applies to **delegated-mode connector tools** —
+  e.g. Codex's `send_email` — and is enforced at the
+  `/api/integrations/:key/exec` task-mode chokepoint via the per-task
+  allowed-tools envelope. In direct mode, the `/api/mail/*` route
+  handler has no equivalent deny check today, so a send call is what
+  it appears to be: a send.) When you judge the user would want to
+  know about a send immediately (e.g. a reply to a stranger), call
+  `POST /api/notify` yourself.
+- Never include `bcc` unless the user explicitly asks for it.
+
+### Replies — RFC-2822 headers are the source of truth
+Provider thread ids (Gmail `threadId`, Graph `conversationId`) differ;
+RFC-2822 `Message-Id` + `References` is the one chain that works across
+all four kinds.
+
+1. Fetch the thread metadata: `GET /api/mail/:acct/threads/:threadId?body=none`
+   (returns `messages[]` in chronological order without raw HTML bodies).
+2. From the last message, pull `rfc822MsgId` and `references`.
+3. Build the `reply` block:
+   ```json
+   {
+     "inReplyToRfc822Id": "<last.rfc822MsgId>",
+     "references": ["<A>", "<B>", "<last.rfc822MsgId>"],
+     "providerThreadId": "<last.threadId>",
+     "parentProviderMsgId": "<last.providerMsgId>"
+   }
+   ```
+   `providerThreadId` is Gmail's `threadId` / Graph's `conversationId`. On
+   IMAP (Yahoo / iCloud) threads are client-walked — omit it there.
+4. For reply-all, build `to` from the original `from` + existing `to`, and
+   `cc` from the original `cc`, excluding the sender account's own email
+   (resolve from `accounts.md`).
+
+If the thread endpoint returns `status: "partial"` with `missingAncestors
+> 0`, reply is still safe (the chain you have is headers-valid), but
+acknowledge to the user that older context wasn't indexed locally.
+
+### Searching — prefer the local index
+For "find emails about X / from Y / last month" queries, start with the
+daemon's local FTS5 index — zero provider round-trips, cross-account:
+
+```bash
+curl -s "http://localhost:8321/api/mail/search?q=invoice+acme&limit=20"
+# Scope to one account: &accountId=<id>
+# Shape: { results: [{ accountId, providerMsgId, subject, snippet,
+#                      receivedAtUtc, from: { email }, isRead }], count, query }
+```
+
+Only fall back to per-account provider search (`/mail/:acct/messages?q=`)
+when you need provider-fresh results or the index doesn't cover the time
+range (fresh installs).
+
+### Reading message bodies — use extracted chunks
+Do not dump full raw HTML mail into a file for `Read`. Large airline,
+receipt, and marketing emails often arrive as one-line compressed HTML and
+can exceed the tool's token/line limits.
+
+For headers/snippet/attachment metadata only, use:
+
+```bash
+curl -s "http://localhost:8321/api/mail/ACCT/messages/MSG?body=none"
+```
+
+For body understanding, fetch the extracted body endpoint first:
+
+```bash
+curl -s "http://localhost:8321/api/mail/ACCT/messages/MSG/body?format=extracted&maxChars=12000"
+```
+
+Shape: `{ content, source, links, images, chunk, hasMore, nextChunk,
+totalChars, rawHtmlAvailable, linkCount, imageCount, nextMetadataOffset }`.
+`content` contains visible body text plus link URLs and image alt/title
+metadata. If `hasMore` is true, request the next content chunk:
+
+```bash
+curl -s "http://localhost:8321/api/mail/ACCT/messages/MSG/body?format=extracted&chunk=1&maxChars=12000"
+```
+
+The structured `links` / `images` arrays are paginated separately so a
+marketing email with thousands of links cannot blow up a response. If
+`nextMetadataOffset` is non-null and you need structured metadata beyond
+what is already rendered in `content`, pass `metadataOffset=<value>`.
+
+Only use `format=raw` when exact markup is required; it is still chunked:
+
+```bash
+curl -s "http://localhost:8321/api/mail/ACCT/messages/MSG/body?format=raw&chunk=0&maxChars=12000"
+```
+
+### When NOT to act
+- During `routine.hourly_check` this skill is **read-only** — no sending,
+  no draft edits, no tag changes, no trash / untrash / archive.
+- No bulk operations without user confirmation.
+- Trash / untrash / archive run autonomously when not on the user's
+  deny list. The daemon does not DM the owner before the call. Single
+  ops only; if you're about to trash 3+ messages at once, stop and ask
+  the user — the agent's own judgment is the gate, not the daemon.
+- **Delegated mode**: this skill body is loaded only when `gmail.mode ===
+  "direct"`. When Gmail is delegated, the materializer picks
+  `SKILL.delegated.<sessionBackend>.md` (cross-backend) or skips the
+  skill entirely (same-backend, native MCP). If you somehow reach
+  `/api/mail/*` from this body while Gmail is delegated, the route
+  returns `410 integration_delegated` — re-read `integrations.md` and
+  use `POST /api/integrations/gmail/exec` (task mode) instead.
+
+## 3. Provider capability matrix
+
+{{> ref:providers }}
+
+## 4. Query grammar
+
+{{> ref:query-grammar }}
+
+## 5. Error handling
+
+{{> ref:errors }}
+
+## 6. Worked examples
+
+### Reply with context
+```bash
+# 1. Find the thread — start local.
+curl -s "http://localhost:8321/api/mail/search?q=from:alice+proposal&limit=5"
+# → pick the hit, note accountId + providerMsgId.
+
+# 2. Fetch the thread.
+curl -s "http://localhost:8321/api/mail/acct-1/threads/THREAD_ID"
+# → last message has rfc822MsgId, references[], providerMsgId.
+
+# 3. Create a draft threaded to it. Drafts are Autonomous tier.
+curl -sX POST "http://localhost:8321/api/mail/acct-1/drafts" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "to": ["alice@example.com"],
+    "subject": "Re: Proposal",
+    "textBody": "Thanks Alice — ...",
+    "reply": {
+      "inReplyToRfc822Id": "<abc@mail.example.com>",
+      "references": ["<root@mail.example.com>", "<abc@mail.example.com>"],
+      "providerThreadId": "THREAD_ID",
+      "parentProviderMsgId": "PARENT_MSG_ID"
+    }
+  }'
+```
+
+### File a message (read + tag + archive)
+```bash
+curl -sX POST "http://localhost:8321/api/mail/acct-1/messages/MSG/read" \
+  -d '{"read": true}'
+curl -sX POST "http://localhost:8321/api/mail/acct-1/messages/MSG/tags" \
+  -d '{"add": ["followup"], "remove": []}'
+curl -sX POST "http://localhost:8321/api/mail/acct-1/messages/MSG/archive"
+```
+On IMAP, confirm `followup` is in `GET /mail/:acct/tags` `.userDefined`
+first — unknown keywords get dropped.
+
+### Cross-account search → pick account → send
+```bash
+# Find recipient's earlier emails across all accounts.
+curl -s "http://localhost:8321/api/mail/search?q=from:bob@acme.com&limit=10"
+# → hits carry accountId. Use whichever account received the earlier thread
+#   so the reply comes from a familiar address.
+
+curl -sX POST "http://localhost:8321/api/mail/acct-2/messages/send" \
+  -H "Content-Type: application/json" \
+  -d '{"to": ["bob@acme.com"], "subject": "...", "textBody": "..."}'
+```
+
+## 7. API reference
+
+Base URL `http://localhost:8321`. `ACCT` = accountId from `accounts.md`.
+
+### Accounts
+```bash
+curl -s "http://localhost:8321/api/mail/accounts?active=1"
+# → { accounts: [{ id, kind, email, label?, authStatus, idleEnabled, active, createdAt }, ...] }
+```
+
+### Search (local FTS5, cross-account)
+```bash
+curl -s "http://localhost:8321/api/mail/search?q=...&limit=50&accountId=ACCT"
+# → { results: [{ accountId, providerMsgId, subject, snippet, receivedAtUtc,
+#                 from: { email } | null, isRead }], count, query }
+```
+
+### Read
+```bash
+# List / search via the provider.
+curl -s "http://localhost:8321/api/mail/ACCT/messages?q=is:unread&limit=20"
+# → { messages: [{ providerMsgId, threadId, from, subject, snippet,
+#                  receivedAtUtc, isRead, flags, hasAttachment }] }
+
+curl -s "http://localhost:8321/api/mail/ACCT/messages/MSG_ID"
+# → { message: { ..., body: { text, html }, attachments: [...] } }
+
+curl -s "http://localhost:8321/api/mail/ACCT/threads/THREAD_ID"
+# → { thread: { threadId, messages: [...], status: "full"|"partial", missingAncestors? } }
+
+curl -s "http://localhost:8321/api/mail/ACCT/folders"
+curl -s "http://localhost:8321/api/mail/ACCT/tags"
+```
+
+### Send / draft
+```bash
+# Direct send — Autonomous; rejected with 403 when the user has denied
+# the send tool. Call /api/notify yourself if the user should know.
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/send" \
+  -H "Content-Type: application/json" \
+  -d '{"to": [...], "subject": "...", "textBody": "...", "reply"?: {...}}'
+# → { result: { id, isDraft: false, rfc822MsgId?, warnings? } }
+
+# Draft CRUD — Autonomous tier.
+curl -s "http://localhost:8321/api/mail/ACCT/drafts"
+curl -s "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID"
+curl -sX POST   "http://localhost:8321/api/mail/ACCT/drafts" -d '{...}'
+curl -sX PATCH  "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID" -d '{...}'
+# PATCH response: { status, id, warnings? }
+# - On Outlook, `warnings: ["reply_threading_immutable_after_create"]` if
+#   `reply` was supplied — reply headers are fixed at createDraft time.
+curl -sX DELETE "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID"
+curl -sX POST   "http://localhost:8321/api/mail/ACCT/drafts/DRAFT_ID/send"
+```
+
+### Modify / move
+```bash
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/read"    -d '{"read": true}'
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/tags"    -d '{"add": ["Starred"], "remove": []}'
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/trash"
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/untrash"
+curl -sX POST "http://localhost:8321/api/mail/ACCT/messages/MSG_ID/archive"
+```
+
+### Health
+```bash
+curl -s "http://localhost:8321/api/mail/ACCT/health"
+# → { accountId, lastPollAtUtc, lastError, lastErrorAtUtc,
+#     consecutiveErrorCount, idleFallbackUntilUtc }
+```

package/agent-assets/skills/mail/references/errors.md

@@ -0,0 +1,17 @@
+---
+kind: reference
+parent_skill: mail
+---
+
+Direct-mode write routes share `{ error: string, message: string, detail?: string }`. Map by the `error` code first, then `detail` for richer disambiguation.
+
+| HTTP | `error` | `detail` | What it means / what to do |
+|---|---|---|---|
+| 400 | `provider_not_enabled` | `kind_not_enabled` | The provider is authenticated but the user disabled that provider in settings. Tell the user and stop. |
+| 400 | `provider_not_enabled` | `account_inactive` | This specific account is paused. Tell the user to re-enable it in the dashboard. Stop. |
+| 400 | `provider_not_enabled` | `account_unhealthy` | **Credentials broken** (refresh rejected / app password expired). Tell the user to re-authenticate at `/connections/mail#<accountId>`. Stop. Do NOT treat as "provider disabled." |
+| 404 | `not_found` | — | Account id unknown or message/thread id gone. First retry: re-resolve via `?active=1` (§1). If still 404, surface to user. |
+| 410 | `integration_delegated` | — | Gmail flipped to delegated mode mid-session. This skill body is direct-only — re-read `integrations.md` and use `POST /api/integrations/gmail/exec` (cross-backend task mode) or your session backend's native Gmail MCP (the same-backend variant) instead. |
+| 501 | `not_implemented` | — | Operation unavailable on this provider kind (e.g. IMAP draft writes, Outlook attachment download). Fall back to the provider's native UI and tell the user. |
+| 502 | `provider_auth_error` | — | Upstream rejected the credentials mid-call. Re-consent needed. Do NOT retry; tell the user. |
+| other 5xx | — | — | Transient. Backoff, one retry, then surface the error text. |

package/agent-assets/skills/mail/references/providers.md

@@ -0,0 +1,40 @@
+---
+kind: reference
+parent_skill: mail
+---
+
+Each provider supports the unified surface but with differing semantics.
+Routes return **HTTP 501 `not_implemented`** when a method isn't available
+on this kind — do NOT retry; tell the user and fall back.
+
+| Operation | Gmail | Outlook | Yahoo / iCloud (IMAP) |
+|---|---|---|---|
+| Read, search, list folders | ✅ | ✅ | ✅ (ASCII; non-ASCII degrades — see §4) |
+| Direct send (`POST /messages/send`) | ✅ | ✅ | ✅ |
+| `markRead` / `tags` / `trash` | ✅ | ✅ | ✅ |
+| `archive` / `untrash` | ✅ | ✅ | ✅ |
+| Thread read (`GET /threads/:id`) | ✅ | ✅ | ⚠️ client-walked; `status: "partial"` possible |
+| Draft read (`GET /drafts`, `GET /drafts/:id`) | ✅ | ✅ | ✅ |
+| Draft write (`POST`/`PATCH`/`DELETE /drafts`, `POST /drafts/:id/send`) | ✅ | ✅ | ❌ **501** — direct `/messages/send` only |
+| Attachment download (via `/receipts/:id/file`) | ✅ | ❌ 501 | ❌ 501 |
+
+**IMAP drafts** (Yahoo / iCloud): every draft *write* returns 501. To
+queue outbound mail for a non-Gmail IMAP user, send directly via
+`POST /messages/send` (agent composes body) or ask the user to compose in
+their native client. MIME-constructed drafts ship in a later phase.
+
+**Attachments beyond Gmail**: receipts / attachment download currently
+work only for Gmail messages. If the user asks you to save an attachment
+off an Outlook or IMAP message, say so and point them to the provider's
+web UI.
+
+### Provider-specific quirks
+
+| Concern | Gmail / Outlook | Yahoo / iCloud (IMAP) |
+|---|---|---|
+| Tag semantics | Gmail: label ids. Outlook: category names. Free-form. | System flags only (`\Seen \Flagged \Answered`) + server-advertised `PERMANENTFLAGS` keywords. Unknown tags silently dropped. |
+| Threads | Provider-authoritative | Client-walked from `In-Reply-To` + `References`. `status: "partial"` when local index lacks older ancestors. `404 not_found` if the rfc822 id can't be reached. |
+| `PATCH /drafts/:id` with `reply` | Gmail: threading is editable. Outlook: silently ignores `reply`; response includes `warnings: ["reply_threading_immutable_after_create"]` — create a fresh draft to reshape threading. | N/A (draft writes 501) |
+
+Call `GET /api/mail/:acct/tags` before tagging on IMAP — `userDefined` is
+often empty on servers that don't advertise keywords.

package/agent-assets/skills/mail/references/query-grammar.md

@@ -0,0 +1,24 @@
+---
+kind: reference
+parent_skill: mail
+---
+
+One grammar, translated per-provider:
+
+| Token | Meaning |
+|---|---|
+| `from:<email>` | sender match |
+| `to:<email>` | recipient match |
+| `subject:"..."` | substring of subject |
+| `has:attachment` | ≥ 1 attachment |
+| `is:unread` | unread only |
+| `newer_than:<N>d` | received in last N days |
+| `older_than:<N>d` | received before N days |
+| `<free text>` | subject / body / from |
+
+**Non-ASCII and IMAP.** Before running a non-ASCII free-text query
+against an IMAP account, check `accounts.md` `kind` column. For `yahoo`
+/ `icloud`, the route downgrades to client-side filtering over recent
+UIDs — historic ranges will be **incomplete**. Either (a) keep the
+window short with `newer_than:30d`, (b) use the local FTS5 endpoint
+instead, or (c) tell the user results may miss older matches.