surface-cli 0.3.0 → 0.3.3

package/README.md

@@ -1,279 +1,300 @@
 # Surface CLI
 
-A lean, local-first mail CLI for multi-provider, multi-account email.
+Outlook and Gmail from one local, JSON-first mail CLI.
 
-Surface normalizes Gmail and Outlook behind one contract, keeps local state in SQLite,
-stores auth/cache/downloads under `~/.surface-cli`, and prints machine-readable JSON to
-stdout for automation.
+Surface solves the annoying mail automation case: you have a school or work
+Microsoft 365 account, IMAP is disabled, Graph app permissions need tenant admin
+approval, and normal mail CLIs stop there. Surface uses the Outlook web session
+you can already access in Chrome, so there is no Microsoft app registration,
+Graph permission grant, tenant consent, or IMAP toggle to ask IT for.
 
-## Current V1 Shape
+If you can sign in to Outlook on the web, Surface can give your agent a local
+CLI for that mailbox.
 
-Top-level groups:
+Surface is especially useful for coding agents and personal assistants because it
+keeps mail work compact:
 
-- `surface account`
-- `surface auth`
-- `surface session`
-- `surface mail`
-- `surface attachment`
-- `surface cache`
+- one CLI contract for Gmail and Outlook
+- multi-account support with stable account names
+- stable `thread_ref`, `message_ref`, `attachment_id`, and `session_id` values
+- thread-first `search` and `fetch-unread` results
+- optional automatic summaries for search/fetch triage, with cached summary reuse
+  so repeated checks do not keep bloating context
+- local SQLite state, cached bodies, auth profiles, and downloads under
+  `~/.surface-cli`
+- first-class headless/remote setup for Mac mini, VM, or server hosts
 
-Current command surface:
+Surface is not an admin bypass. It uses the same mailbox access you already have.
+If your organization blocks Outlook on the web or browser automation entirely,
+Surface cannot override that policy.
 
-```bash
-surface account add work --provider gmail --email me@company.com
-surface account add school --provider outlook --email me@school.edu
-surface account identity set school --name "Your Name" --name-alias "FirstName"
-surface account identity show school
-
-surface auth login work
-surface auth status
-surface auth logout school
+## Fast Install
 
-surface session start --account school
-surface session list
-surface session stop sess_01...
+Surface requires Node.js 20 or newer.
 
-surface mail fetch-unread --account work --limit 25
-surface mail fetch-unread --account school --session sess_01... --limit 25
-surface mail search --account work --text invoice --subject overdue --limit 10
-surface mail search --account school --session sess_01... --from billing@vendor.com --limit 10
-surface mail search --account work --from billing@vendor.com --mailbox inbox --label unread --limit 10
-surface mail thread get thr_01... --refresh --session sess_01...
-surface mail read msg_01... --refresh --session sess_01...
-surface mail send --account school --to me@example.com --subject "hello" --body "test"
-surface mail send --account school --to me@example.com --subject "hello" --body "test" --draft
-surface mail reply msg_01... --body "Thanks"
-surface mail reply-all msg_01... --body "Thanks all"
-surface mail forward msg_01... --to me@example.com --body "FYI"
-surface mail archive msg_01...
-surface mail rsvp msg_01... --response tentative
+Install the CLI first:
 
-surface attachment list msg_01...
-surface attachment download msg_01... att_01...
-
-surface cache stats
-surface cache prune
-surface cache clear --account work
+```bash
+npm install -g surface-cli
+surface --help
 ```
 
-## Core Decisions
+Then install the skill for the agent you use.
 
-- `fetch-unread` is the public command name.
-- Threads are the top-level result unit.
-- Messages are elements within a thread.
-- `thread get` takes a stable `thread_ref`.
-- `read` takes a stable `message_ref`.
-- Attachment download is separate from `read`.
-- Machine-facing commands emit JSON on stdout.
-- SQLite is the local source of truth for refs and cache metadata.
-- Account-owner identity is stored in SQLite and used so summaries can interpret `needs_action`
-  from the selected account owner's perspective.
+### OpenClaw
 
-See the source-of-truth docs for the exact contracts:
+OpenClaw installs the hosted Surface skill from ClawHub:
 
-- `docs/cli-contract.md`
-- `docs/provider-contract.md`
-- `docs/cache-and-db.md`
-- `docs/config.md`
-
-## Current Implementation Status
+```bash
+openclaw skills install surface-cli
+openclaw skills check
+```
 
-The repo now contains a working TypeScript scaffold under `src/`:
+If `openclaw skills check` reports the `surface` binary as missing, run
+`npm install -g surface-cli` on that same machine.
 
-- CLI entrypoint and command groups
-- config loading from `~/.surface-cli/config.toml`
-- SQLite-backed local account state
-- adapter registry for `gmail-api` and `outlook-web-playwright`
-- donor normalization utilities ported from the legacy Surface repo for Gmail and Outlook
-- Gmail OAuth login wired to Google desktop-app OAuth with stored refresh tokens under `~/.surface-cli/auth/<account_id>/gmail-token.json`
-- live Gmail `fetch-unread`, structured `search`, `thread get`, `read`, `attachment list`, `attachment download`, `send`, `reply`, `reply-all`, `forward`, `archive`, `mark-read`, `mark-unread`, `rsvp`, and `--draft` on send-like actions
-- Outlook Playwright auth lifecycle wired to persistent profiles under `~/.surface-cli/auth/<account_id>/profile`
-- live Outlook `fetch-unread`, structured `search`, `thread get`, `read`, `attachment list`, `attachment download`, `send`, `reply`, `reply-all`, `forward`, `archive`, `mark-read`, `mark-unread`, `rsvp`, and `--draft` on send-like actions
-- explicit warm session ids for Outlook read-path chaining (`session start/list/stop`, plus `--session` on `search`, `fetch-unread`, `thread get --refresh`, and `read`)
-- summary backends for `openrouter` and `openclaw`, with `openai/gpt-5.4-mini` as the default
-  OpenRouter summarizer model when summarization is enabled
-- lean opt-in Outlook v1 and Gmail v1 live e2e coverage via `npm run e2e:outlook-v1` and `npm run e2e:gmail-v1`
+### Codex
 
-What is still intentionally incomplete:
+Codex reads user skills from `~/.agents/skills`:
 
-- draft lifecycle commands
-- move / delete
-- broader automated coverage beyond the opt-in provider v1 e2e scripts and cache-prune policy
+```bash
+mkdir -p ~/.agents/skills/surface-cli
+curl -fsSL https://raw.githubusercontent.com/VishalJ99/surface-cli/main/skills/surface-cli/SKILL.md \
+  -o ~/.agents/skills/surface-cli/SKILL.md
+```
 
-## Setup
+Restart Codex if the skill does not appear immediately. Codex can invoke it
+automatically from the description, or you can mention `$surface-cli`.
 
-Surface supports two setup modes:
+### Claude Code
 
-- standard single-machine setup
-  Surface runs on the same machine where you can access the browser, localhost callback ports,
-  and any required GUI prompts
-- headless remote setup
-  Surface runs on a remote machine such as a Mac mini, while a second local machine helps with
-  Gmail OAuth browser approval or Outlook browser-profile bootstrap
+Claude Code reads personal skills from `~/.claude/skills`:
 
-The correct split is:
+```bash
+mkdir -p ~/.claude/skills/surface-cli
+curl -fsSL https://raw.githubusercontent.com/VishalJ99/surface-cli/main/skills/surface-cli/SKILL.md \
+  -o ~/.claude/skills/surface-cli/SKILL.md
+```
 
-- the machine that actually runs `surface` for day-to-day mail work is the canonical Surface host
-- that host owns:
-  - `~/.surface-cli/state.db`
-  - `~/.surface-cli/auth/`
-  - `~/.surface-cli/cache/`
-  - `~/.surface-cli/downloads/`
-- `~/.surface-cli/config.toml` is auto-created on first run and stores local policy only
-  such as summarizer and write-safety settings
-- account registry and auth state do not live in `config.toml`
-- existing config files are not rewritten on upgrade; if an older config names
-  `summarizer_model = "openai/gpt-4o-mini"`, change it to
-  `summarizer_model = "openai/gpt-5.4-mini"` for the current recommended default
+Claude Code exposes the skill as `/surface-cli` and may also load it
+automatically when the task matches the skill description.
 
-### Install Surface
+## Setup
 
-For development from a checkout:
+Add the accounts you want Surface to manage:
 
 ```bash
-npm install
-npm run build
-npm link
+surface account add uni --provider outlook --email you@school.edu
+surface account add personal --provider gmail --email you@gmail.com
+surface account list
 ```
 
-For a published install, use npm:
+For Outlook school/work accounts, set the mailbox owner's identity explicitly.
+This helps summaries decide whether a thread needs action from you:
 
 ```bash
-npm install -g surface-cli
+surface account identity set uni \
+  --email you@school.edu \
+  --name "Your Name" \
+  --name-alias "FirstName"
 ```
 
-### Standard Single-Machine Setup
+Log in:
 
-Use this when the same machine can:
+```bash
+surface auth login uni
+surface auth status uni
+```
 
-- open Chrome locally
-- receive loopback OAuth callbacks on `localhost`
-- show any required Microsoft or Google auth UI
+Outlook auth opens Chrome and stores a dedicated browser profile under
+`~/.surface-cli/auth/<account_id>/profile`. You do not need Azure, Graph, IMAP,
+Exchange app passwords, or admin approval. You do need Chrome and the ability to
+complete your normal Microsoft sign-in flow.
 
-Typical flow:
+For Gmail, `surface auth login <account>` uses a Google desktop OAuth client and
+stores the refresh token under `~/.surface-cli/auth/<account_id>/`. Place the
+client secret at `./client_secret.json` or set `SURFACE_GMAIL_CLIENT_SECRET_FILE`.
 
-1. install Surface on that machine
-2. add accounts there
-3. optionally set account-owner name/aliases with `surface account identity set <account> ...`
-4. run `surface auth login <account>` there
-5. use that same machine for normal `surface mail ...` commands
+## Headless Remote Setup
 
-Gmail:
+Surface is designed for remote hosts, including a Mac mini or other headless box
+running OpenClaw, Codex, or Claude Code.
 
-- place a Google desktop OAuth client secret at `./client_secret.json` or set
-  `SURFACE_GMAIL_CLIENT_SECRET_FILE`
-- add the account first:
-  - `surface account add personal --provider gmail --email you@example.com`
-- run:
-  - `surface auth login personal`
-- Gmail auth verifies the mailbox email and updates account-owner identity automatically.
+The rule is simple: install Surface and the agent skill on the machine where the
+agent will run day to day. That machine is the canonical Surface host and owns:
 
-For Outlook auth:
+```text
+~/.surface-cli/state.db
+~/.surface-cli/auth/
+~/.surface-cli/cache/
+~/.surface-cli/downloads/
+```
+
+Use your laptop only as an auth helper when the host cannot show a browser.
 
-- `surface auth login <account>` opens Chrome against the account profile directory
-- `surface auth status [account]` probes Outlook headlessly and reports whether the profile lands in the mailbox or a sign-in flow
-- `surface auth logout <account>` clears the stored Outlook profile for that account
-- if the Outlook account email is opaque or placeholder-like, set identity explicitly:
-  - `surface account identity set uni --email you@school.edu --name "Your Name" --name-alias "FirstName"`
+For example, if OpenClaw runs on a Mac mini, install both pieces there:
 
-### Headless Remote Setup
+```bash
+ssh macmini 'npm install -g surface-cli && openclaw skills install surface-cli'
+```
 
-Use this when your real Surface host is remote, for example a headless Mac mini, VM, or server.
+If Codex or Claude Code runs on the remote host instead, run the matching skill
+install command from the Fast Install section inside that remote shell.
 
-In this mode:
+Outlook remote setup:
 
-- install Surface on the remote machine first
-- add accounts on the remote machine first
-- set account-owner identity on the remote machine when the mailbox address is opaque or
-  placeholder-like
-- the remote machine is the source of truth for all Surface state
-- install Surface locally too if you want to use `--remote-host` auth helpers
-- `--remote-host` assumes the named account already exists on the remote machine
-- remote auth only warns before replacement when the remote account already reports `authenticated`
-- if the remote auth-state probe times out or fails, Surface proceeds without an overwrite warning
-  instead of blocking the remote auth flow
+```bash
+ssh macmini 'surface account add uni --provider outlook --email you@school.edu'
+ssh macmini 'surface account identity set uni --email you@school.edu --name "Your Name"'
 
-#### Gmail On A Headless Remote Host
+surface auth login uni --remote-host macmini
+ssh macmini 'surface auth status uni'
+```
 
-The remote host is the real Surface runtime. Your local machine is only a browser helper.
+The remote Outlook auth flow opens Chrome locally, lets you complete Microsoft
+sign-in on your laptop, syncs the dedicated Surface browser profile to the remote
+host, then validates it there.
 
-1. on the remote host, install Surface, add the Gmail account, and optionally set identity aliases
-2. on the local machine, ensure `surface` is installed too
-3. on the local machine, run:
+Gmail uses the same public remote command:
 
 ```bash
-surface auth login <gmail-account> --remote-host <ssh-host>
+surface auth login personal --remote-host macmini
 ```
 
-What happens:
-
-- Surface starts SSH port forwarding first
-- Surface reuses the remote account's stored `client_secret.json` when present
-- Surface runs the Gmail OAuth listener on the remote host
-- if the remote host does not already have Gmail OAuth client credentials stored for that account,
-  Surface falls back to a local `client_secret.json` or `SURFACE_GMAIL_CLIENT_SECRET_FILE`
-- you open the Google auth URL locally
-- the OAuth callback is forwarded back to the remote host
-- the refresh token is stored on the remote host under `~/.surface-cli/auth/<account_id>/`
+For Gmail, Surface starts SSH port forwarding so the OAuth callback lands on the
+remote Surface process and the refresh token is stored on the remote host.
 
-#### Outlook On A Headless Remote Host
+## Token-Efficient Mail Triage
 
-The remote host is again the real Surface runtime. Your local machine is only an auth/bootstrap
-helper.
+Surface commands print JSON on stdout. Agents should parse the JSON and act on
+stable refs rather than scraping terminal text or copying whole mail bodies into
+chat.
 
-1. on the remote host, install Surface, add the Outlook account, and set identity aliases if needed
-2. on the local machine, ensure `surface` is installed too
-3. on the local machine, run:
+Fetch unread threads:
 
 ```bash
-surface auth login <outlook-account> --remote-host <ssh-host>
+surface mail fetch-unread --account uni --limit 10
+surface mail sync-unread-state --account uni --limit 50
 ```
 
-What happens:
+List recent sent messages:
 
-- Surface opens local Chrome in a dedicated Surface profile
-- you complete the Microsoft sign-in locally
-- Surface syncs that profile to the remote host
-- Surface validates the copied profile on the remote host with `surface auth status <account>`
-
-This is why headless remote auth currently requires `surface` to exist on both machines:
+```bash
+surface mail sent --account uni
+surface mail sent --account uni --recipient person@example.com --limit 10
+```
 
-- local machine: helper for browser/UI work
-- remote machine: canonical Surface runtime and state owner
+`sent` is message-first: the default limit is the last 10 sent messages, and each result includes a
+stable `thread_ref` so agents can open the full conversation when needed.
 
-If Chrome is installed in a non-default location, set:
+Search with structured filters:
 
 ```bash
-export SURFACE_CHROME_PATH="/absolute/path/to/Google Chrome"
+surface mail search --account uni --from registrar@school.edu --subject "deadline" --limit 10
+surface mail search --account personal --mailbox inbox --label unread --text "invoice" --limit 10
 ```
 
-For the live Outlook v1 e2e script:
+Read only the thread or message you need:
 
 ```bash
-export SURFACE_E2E_ENABLE=1
-export SURFACE_TEST_RECIPIENTS='sender@example.com,recipient@example.com,observer@example.com'
-export SURFACE_TEST_ACCOUNT_ALLOWLIST='uni'
-npm run e2e:outlook-v1
+surface mail thread get thr_01...
+surface mail thread get thr_01... --refresh
+surface mail read msg_01...
+surface mail read msg_01... --refresh
 ```
 
-For the live Gmail v1 e2e script:
+For Outlook-heavy sessions, start a warm browser session and pass its `session_id`
+to follow-up read commands:
 
 ```bash
-export SURFACE_E2E_ENABLE=1
-export SURFACE_E2E_ACCOUNT='personal_2'
-npm run e2e:gmail-v1
+surface session start --account uni
+surface mail fetch-unread --account uni --session sess_01... --limit 10
+surface mail sync-unread-state --account uni --session sess_01... --limit 50
+surface mail sent --account uni --session sess_01... --limit 10
+surface mail search --account uni --session sess_01... --text "exam board" --limit 10
+surface session stop sess_01...
 ```
 
-For live write-path testing, also set:
+Optional summaries are controlled locally. New configs default to
+`summarizer_backend = "none"` so mail reads never require paid or external model
+calls unless you opt in. To enable summaries, set `summarizer_backend` in
+`~/.surface-cli/config.toml` or `SURFACE_SUMMARIZER_BACKEND` in the environment.
+
+Supported summary backends:
+
+- `openrouter`, using `OPENROUTER_API_KEY`
+- `openclaw`, using the local `openclaw` CLI
+
+When summaries are enabled, Surface summarizes a capped canonical per-thread
+payload, stores summary fingerprints in SQLite, and reuses matching summaries on
+later checks. This keeps recurring inbox watches and searches from repeatedly
+feeding unchanged threads back into your agent context.
+
+Email content may be sent to the configured summarizer provider when summaries
+are enabled. Keep `summarizer_backend = "none"` if all mail content must remain
+local to the provider and Surface cache.
+
+## Common Commands
 
 ```bash
-export SURFACE_WRITES_ENABLED=1
-export SURFACE_SEND_MODE=allow_send
-export SURFACE_TEST_RECIPIENTS='sender@example.com,recipient@example.com,observer@example.com'
-export SURFACE_TEST_ACCOUNT_ALLOWLIST='uni'
+surface account list
+surface account identity show uni
+
+surface auth status
+surface auth logout uni
+
+surface mail fetch-unread --account uni --limit 25
+surface mail sync-unread-state --account uni --limit 50
+surface mail search --account uni --text "project update" --limit 10
+surface mail thread get thr_01... --refresh
+surface mail read msg_01... --refresh
+
+surface attachment list msg_01...
+surface attachment download msg_01... att_01...
+
+surface mail send --account uni --to you@example.com --subject "hello" --body "test" --draft
+surface mail reply msg_01... --body "Thanks" --draft
+surface mail archive msg_01...
+surface mail mark-read msg_01...
+surface mail mark-unread msg_01...
+surface mail rsvp msg_01... --response tentative
+
+surface cache stats
+surface cache prune
 ```
 
-## Local State
+Write actions are guarded by local policy in `~/.surface-cli/config.toml` and
+`SURFACE_*` environment variables. Use `--draft` for safe compose flows unless
+you have explicitly enabled live sends.
+
+## What Works Today
+
+Surface v1 supports:
+
+- Gmail via Google APIs
+- Outlook via Outlook Web and Playwright
+- account add/list/remove
+- auth login/status/logout
+- account-owner identity for summaries
+- `search`, `fetch-unread`, and message-first `sent`
+- bounded unread-state refresh with `sync-unread-state`
+- thread refresh and message read
+- attachment list/download
+- send/reply/reply-all/forward with `--draft`
+- archive, mark-read, mark-unread, RSVP
+- Outlook warm sessions for repeated read-path commands
+- optional summaries through OpenRouter or OpenClaw
+
+Intentionally incomplete:
+
+- draft lifecycle commands
+- move/delete
+- broad automated live coverage beyond the opt-in Gmail and Outlook v1 e2e
+  scripts
+
+## State And Config
+
+Surface stores local state under `~/.surface-cli`:
 
 ```text
 ~/.surface-cli/
@@ -290,6 +311,26 @@ export SURFACE_TEST_ACCOUNT_ALLOWLIST='uni'
       <message_ref>/
 ```
 
+`config.toml` stores local policy and preferences only. Account registry, auth
+material, cache metadata, and account-owner identity live in SQLite and auth
+storage, not in `config.toml`.
+
+## Contract Docs
+
+These are the source-of-truth docs for behavior changes:
+
+- `docs/cli-contract.md`
+- `docs/provider-contract.md`
+- `docs/cache-and-db.md`
+- `docs/config.md`
+- `docs/decisions/`
+
+External skill docs:
+
+- OpenClaw skills: https://docs.openclaw.ai/cli/skills
+- Codex skills: https://developers.openai.com/codex/skills
+- Claude Code skills: https://code.claude.com/docs/en/skills
+
 ## Development
 
 ```bash
@@ -299,22 +340,47 @@ npm run build
 npm run surface -- --help
 ```
 
+For live Outlook v1 e2e:
+
+```bash
+export SURFACE_E2E_ENABLE=1
+export SURFACE_TEST_RECIPIENTS='sender@example.com,recipient@example.com,observer@example.com'
+export SURFACE_TEST_ACCOUNT_ALLOWLIST='uni'
+npm run e2e:outlook-v1
+```
+
+For live Gmail v1 e2e:
+
+```bash
+export SURFACE_E2E_ENABLE=1
+export SURFACE_E2E_ACCOUNT='personal'
+npm run e2e:gmail-v1
+```
+
+For live write-path testing:
+
+```bash
+export SURFACE_WRITES_ENABLED=1
+export SURFACE_SEND_MODE=allow_send
+export SURFACE_TEST_RECIPIENTS='sender@example.com,recipient@example.com,observer@example.com'
+export SURFACE_TEST_ACCOUNT_ALLOWLIST='uni'
+```
+
 ## Publish To ClawHub
 
-ClawHub publishes the skill folder, not the whole repo. The publish unit is:
+ClawHub publishes the skill folder, not the whole repo:
 
 ```text
 skills/surface-cli/
   SKILL.md
 ```
 
-Recommended release order:
+Release order:
 
-1. publish the CLI package to npm so ClawHub can install `surface`
-2. log into ClawHub
+1. publish the CLI package to npm so the skill can install `surface`
+2. sync the intended `SKILL.md` into the active OpenClaw workspace if needed
 3. publish the skill folder
-
-Example:
+4. inspect the hosted skill
 
 ```bash
 npm publish
@@ -324,6 +390,9 @@ clawhub publish ./skills/surface-cli \
   --name "Surface CLI" \
   --version <version> \
   --changelog "<release notes>"
+
+clawhub inspect surface-cli --json
+clawhub inspect surface-cli --file SKILL.md
 ```
 
 Before publishing, verify the package payload:

package/dist/cli.js

@@ -9,9 +9,11 @@ import { toPublicThread } from "./lib/public-mail.js";
 import { runRemoteAuthLogin } from "./lib/remote-auth.js";
 import { loadStoredThread, threadHasReadableCache } from "./lib/stored-mail.js";
 import { nowIsoUtc } from "./lib/time.js";
+import { syncUnreadState } from "./lib/unread-state.js";
 import { resolveProviderAdapter } from "./providers/index.js";
 import { createAccountRuntimeContext, createRuntimeContext } from "./runtime.js";
-import { DEFAULT_SESSION_IDLE_TIMEOUT_SECONDS, DEFAULT_SESSION_MAX_AGE_SECONDS, listWarmSessions, sessionFetchUnread, sessionReadMessage, sessionRefreshThread, sessionSearch, sessionStartEnvelope, startWarmSession, stopWarmSession, } from "./session.js";
+import { DEFAULT_SESSION_IDLE_TIMEOUT_SECONDS, DEFAULT_SESSION_MAX_AGE_SECONDS, listWarmSessions, sessionFetchUnread, sessionReadMessage, sessionRefreshThread, sessionSearch, sessionSent, sessionStartEnvelope, startWarmSession, stopWarmSession, } from "./session.js";
+const DEFAULT_SENT_LIMIT = 10;
 function positiveInt(value) {
     const parsed = Number.parseInt(value, 10);
     if (!Number.isFinite(parsed) || parsed <= 0) {
@@ -454,6 +456,48 @@ mailCommand
         });
     });
 });
+mailCommand
+    .command("sent")
+    .description("List recent sent messages.")
+    .requiredOption("--account <account>", "Logical account name")
+    .option("--session <session_id>", "Use a warm session id")
+    .option("--recipient <email>", "Recipient filter for sent messages")
+    .addOption(new Option("--limit <limit>", "Max sent messages to return").argParser(positiveInt))
+    .action(async (options, command) => {
+    await runAccountAction(command.optsWithGlobals(), options.account, async (context) => {
+        const recipient = normalizeOptionalString(options.recipient);
+        const query = {
+            ...(recipient ? { recipient } : {}),
+            limit: options.limit ?? DEFAULT_SENT_LIMIT,
+        };
+        const messages = options.session
+            ? await sessionSent(context, options.session, query)
+            : await resolveProviderAdapter(context.account).fetchSent(context.account, query, context);
+        writeJson({
+            schema_version: "1",
+            command: "sent",
+            generated_at: nowIsoUtc(),
+            account: context.account.name,
+            query,
+            messages,
+        });
+    });
+});
+mailCommand
+    .command("sync-unread-state")
+    .requiredOption("--account <account>", "Logical account name")
+    .option("--session <session_id>", "Use a warm session id")
+    .addOption(new Option("--limit <limit>", "Max unread threads to fetch and local candidates to compare").argParser(positiveInt))
+    .option("--rebaseline", "Clear local unread for the account before repopulating fetched unread", false)
+    .action(async (options, command) => {
+    await runAccountAction(command.optsWithGlobals(), options.account, async (context) => {
+        writeJson(await syncUnreadState(context, {
+            limit: options.limit ?? context.config.defaultResultLimit,
+            rebaseline: Boolean(options.rebaseline),
+            ...(options.session ? { session: options.session } : {}),
+        }));
+    });
+});
 mailCommand
     .command("thread")
     .description("Inspect thread state.")