@wirecat/cli-core 0.553.0 → 0.555.0

package/dist/mail/cli/review.d.ts

@@ -0,0 +1,24 @@
+import { Command } from "commander";
+import type { MailReads } from "./index.js";
+/** Where a mail review starts: a time only; one thread is `conversations show`. */
+export declare const MAIL_REVIEW_QUERY: import("@wirecat/cli-base/query").QueryRegistry;
+/** The mail review's steps; a host lists them beside its own so its step checks know them. */
+export declare const MAIL_REVIEW_STEPS: ({
+    id: string;
+    kind: "command";
+    command: string;
+    args: {
+        name: string;
+        required: boolean;
+    }[];
+    why: string;
+} | {
+    id: string;
+    kind: "user_action";
+    why: string;
+})[];
+/**
+ * `review` over the stored mail of the profile's mailbox, with tg's words: what is new, what the owner owes, what
+ * waits for an answer. It reads the store only and opens no task.
+ */
+export declare const mailReviewCommand: (mail: MailReads) => Command;

package/dist/mail/cli/review.js

@@ -0,0 +1,204 @@
+import { CliError } from "@wirecat/cli-base";
+import { annotate } from "@wirecat/cli-base/commands";
+import { defineQuery } from "@wirecat/cli-base/query";
+import { defineSteps, stepOf } from "@wirecat/cli-base/standards";
+import { Command } from "commander";
+import { environmentOf, outputFor } from "../../cli/context.js";
+import { LOCAL_READ } from "../../cli/effects.js";
+import { listOf, renderAnswer } from "../../cli/envelope.js";
+import { listQuery, nativeField, nativeTerms, queryHelp, typedQuery } from "../../cli/list-query.js";
+import { pointsOf } from "../../cli/messenger/catch-up.js";
+import { catchUpQuery, summaryOf } from "../../cli/messenger/catch-up-answers.js";
+import { messageItem } from "../../cli/messenger/message-items.js";
+import { checkPoints } from "../../cli/messenger/points.js";
+import { unansweredHours } from "../../cli/messenger/review.js";
+import { parseDuration } from "../../domain/duration.js";
+import { formatReference } from "../../domain/references.js";
+import { AGENDA_DEFAULTS } from "../../services/agenda.js";
+import { REVIEW_DAYS, reviewStart } from "../../services/inbox.js";
+import { hitText } from "../read.js";
+import { OWED_DAYS, REVIEW_THREADS, reviewMail } from "../review.js";
+const DAY = 86_400_000;
+/** Where a mail review starts: a time only; one thread is `conversations show`. */
+export const MAIL_REVIEW_QUERY = defineQuery({
+    entity: "message",
+    backend: "native",
+    fields: [
+        nativeField({ name: "date", type: "time", operators: ["range"], example: "date>2h" }),
+        nativeField({ name: "bulk", type: "kw", operators: ["term"], example: "bulk:false" }),
+    ],
+});
+/** The mail review's steps; a host lists them beside its own so its step checks know them. */
+export const MAIL_REVIEW_STEPS = defineSteps([
+    {
+        id: "mail-review.next",
+        command: "review",
+        args: [{ name: "query", required: true }],
+        why: "the next review starts where this one ended",
+    },
+    {
+        id: "mail-conversations.show",
+        command: "conversations show",
+        args: [{ name: "conversation", required: true }],
+        why: "only the newest emails of the thread were read here; this reads it whole",
+    },
+]);
+const step = (id) => MAIL_REVIEW_STEPS.find((one) => one.id === id);
+const waitingHours = (value) => value === true ? AGENDA_DEFAULTS.waiting / 3_600_000 : parseDuration(String(value), "--waiting") / 3_600_000;
+const quoted = (value) => `"${value.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+/** A file name for the mailbox's points: they describe the mailbox, whichever profile reads it. */
+const pointsName = (mailbox) => encodeURIComponent(mailbox.account);
+const markText = (marks) => {
+    const said = [
+        marks?.bulk ? "bulk" : "",
+        marks?.listId ? `list ${marks.listId}` : "",
+        marks?.ruleId ? `rule ${marks.ruleId}` : "",
+    ];
+    const shown = said.filter(Boolean).join(" · ");
+    return shown ? `\n  [${shown}]` : "";
+};
+const reviewAnswer = (found, mailbox, fresh) => {
+    const read = found.chats
+        .flatMap((chat) => chat.messages.map((message) => ({ ...message, chatTitle: chat.title })))
+        .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp));
+    const cut = found.chats.filter((chat) => chat.more);
+    const ref = (thread) => formatReference({ type: "chat", ...mailbox, chat: thread });
+    const turns = found.unanswered !== undefined || found.waiting !== undefined;
+    const missing = [
+        ...(cut.length > 0
+            ? [
+                {
+                    field: "items",
+                    why: `only the newest emails of ${cut.length} thread(s)`,
+                    step: "mail-conversations.show",
+                },
+            ]
+            : []),
+        ...(found.skipped.length > 0
+            ? [
+                {
+                    field: "items",
+                    why: `skipped ${found.skipped.length} threads — more than ${REVIEW_THREADS} at once; the next review reads them`,
+                },
+            ]
+            : []),
+        ...(found.quiet > 0
+            ? [{ field: "items", why: `bulk:false left out ${found.quiet} threads of mail sent to many, lists or envelopes` }]
+            : []),
+    ];
+    const next = [
+        ...(!fresh && !turns
+            ? [
+                stepOf(step("mail-review.next"), {
+                    args: { query: `date>${quoted(found.complete ? found.until : found.since)}` },
+                }),
+            ]
+            : []),
+        ...cut.map((chat) => stepOf(step("mail-conversations.show"), { args: { conversation: ref(chat.id) } })),
+    ];
+    return listOf("review", {
+        items: read.map((message) => ({
+            ...summaryOf(message, mailbox),
+            email: {
+                ...messageItem(message, mailbox).email,
+                bulk: message.marks?.bulk ?? false,
+                list_id: message.marks?.listId ?? null,
+                rule_id: message.marks?.ruleId ?? null,
+            },
+        })),
+        limit: Math.max(1, read.length),
+        has_more: false,
+        next,
+        missing,
+        meta: found.complete ? {} : { complete: false },
+    });
+};
+/**
+ * `review` over the stored mail of the profile's mailbox, with tg's words: what is new, what the owner owes, what
+ * waits for an answer. It reads the store only and opens no task.
+ */
+export const mailReviewCommand = (mail) => annotate(new Command("review"), {
+    examples: [
+        `${mail.app.command} personal review "date>2h"`,
+        `${mail.app.command} personal review --new`,
+        `${mail.app.command} personal review --unanswered 1d`,
+        `${mail.app.command} personal review --waiting 7d`,
+    ],
+    effects: LOCAL_READ,
+    partial: true,
+    output: { entity: "message", view: "summary" },
+    query: MAIL_REVIEW_QUERY,
+})
+    .summary("threads with new mail, mail you owe an answer, mail waiting for one")
+    .description("every stored email, yours too, in threads that changed since a point — for reviewing who owes what. " +
+    "It reads what sync stored, so it asks the mail server nothing")
+    .addHelpText("after", queryHelp(MAIL_REVIEW_QUERY))
+    .argument("[query...]", `where the last review ended: date>2h; ${REVIEW_DAYS} days ago if no date`)
+    .option("--unanswered [duration]", "only threads whose newest email came to you, in To or Cc, with no answer for this long — 4h, 1d; 24h if not given")
+    .option("--waiting [duration]", "only threads where you wrote last and nobody answered for this long — 3d; 7d if not given")
+    .option("--new", "what changed since the last `review --new` of this mailbox, a point per thread — for scheduled runs")
+    .addHelpText("after", `
+Without a date, --unanswered and --waiting look at threads active in the last ${OWED_DAYS} days.
+Every email is shown, mail sent to many too; each item's email says bulk, list_id and rule_id, and its sender_score.
+bulk:false leaves out threads whose newest email is mail sent to many, a list's or recorded by an envelope rule.
+Mail newer than the last finished sync waits for the next review. Each reader keeps its own --new point: you,
+an agent over MCP, and each scheduled run.`)
+    .action(async function (query) {
+    const options = this.opts();
+    const { since: from, meta } = catchUpQuery(query, MAIL_REVIEW_QUERY, "review");
+    const bulk = nativeTerms(listQuery(typedQuery(query), MAIL_REVIEW_QUERY, "review"), "review").get("bulk")?.value;
+    if (bulk !== undefined && bulk !== "false")
+        throw new CliError("validation_error", `bulk: takes false — leave it out to see all mail, not "${bulk}"`);
+    const turns = options.unanswered !== undefined || options.waiting !== undefined;
+    if (options.new && (from !== undefined || turns))
+        throw new CliError("validation_error", "--new keeps its own point — not with a date, --unanswered or --waiting");
+    const unanswered = options.unanswered === undefined ? undefined : unansweredHours(options.unanswered);
+    const waiting = options.waiting === undefined ? undefined : waitingHours(options.waiting);
+    const env = environmentOf(this).env ?? process.env;
+    const now = Date.now();
+    const { found, mailbox, saved } = await mail.read(this, async (store, mailbox) => {
+        const saved = options.new
+            ? checkPoints(mail.app, {
+                command: pointsOf(this, "review", mail.app),
+                profile: pointsName(mailbox),
+                env,
+                firstLookMs: REVIEW_DAYS * DAY,
+            })
+            : undefined;
+        const since = from ?? saved?.first ?? (turns ? now - OWED_DAYS * DAY : reviewStart(now));
+        const found = await reviewMail(store, mailbox, {
+            since,
+            now,
+            ...(saved ? { points: saved.chats } : {}),
+            ...(bulk === "false" ? { noBulk: true } : {}),
+            ...(unanswered === undefined ? {} : { unansweredAfterHours: unanswered }),
+            ...(waiting === undefined ? {} : { waitingAfterHours: waiting }),
+        });
+        return { found, mailbox, saved };
+    });
+    const output = outputFor(this);
+    const answer = reviewAnswer(found, mailbox, saved !== undefined);
+    if (meta)
+        answer.meta = { ...meta, ...answer.meta };
+    renderAnswer(this, output, answer, () => {
+        const read = found.chats.flatMap((chat) => chat.messages);
+        if (found.unanswered || found.waiting)
+            output.renderer.note(`${[
+                found.unanswered ? `owed for ${found.unanswered.olderThanHours}h or more` : "",
+                found.waiting ? `waiting ${found.waiting.olderThanHours}h or more` : "",
+            ]
+                .filter(Boolean)
+                .join(", ")}, threads active from ${found.since}`);
+        else
+            output.renderer.note(`from ${found.since} to ${found.until}${found.complete ? "" : ", incomplete"}`);
+        if (found.quiet > 0)
+            output.renderer.note(`bulk:false left out ${found.quiet} threads`);
+        if (read.length === 0)
+            output.renderer.note("nothing new in the stored mail");
+        return read
+            .sort((a, b) => Date.parse(a.timestamp) - Date.parse(b.timestamp))
+            .map((hit) => `${hitText(hit)}${markText(hit.marks)}\n`)
+            .join("");
+    });
+    saved?.save(found.checked ?? {}, found.complete ? { through: found.until } : {});
+});

package/dist/mail/email-input.d.ts

@@ -1,5 +1,7 @@
 import type { EmailInput } from "../store/index.js";
 import type { ParsedMail } from "./parse.js";
 import type { Listed } from "./source.js";
+/** The Date header, or the server's internal date when the header is missing or unreadable. */
+export declare const sentAtOf: (date: string | null, receivedAt: string) => number;
 /** What one read email stores of itself, whichever run read it; where it is filed is the caller's. */
 export declare const parsedEmail: (mail: ParsedMail, item: Listed, header: Record<string, string | boolean>, address: string) => Omit<EmailInput, "mailboxes">;

package/dist/mail/email-input.js

@@ -1,4 +1,9 @@
 import { addressOf } from "./attachments.js";
+/** The Date header, or the server's internal date when the header is missing or unreadable. */
+export const sentAtOf = (date, receivedAt) => {
+    const sent = date === null ? Number.NaN : Date.parse(date);
+    return Number.isNaN(sent) ? Date.parse(receivedAt) : sent;
+};
 /** What one read email stores of itself, whichever run read it; where it is filed is the caller's. */
 export const parsedEmail = (mail, item, header, address) => ({
     externalId: item.messageId,
@@ -7,7 +12,7 @@ export const parsedEmail = (mail, item, header, address) => ({
     to: mail.to.map(addressOf),
     cc: mail.cc.map(addressOf),
     bcc: mail.bcc.map(addressOf),
-    sentAt: null,
+    sentAt: sentAtOf(mail.date, item.receivedAt),
     receivedAt: Date.parse(item.receivedAt),
     bodyText: mail.text || null,
     size: item.size ?? null,

package/dist/mail/index.d.ts

@@ -6,6 +6,7 @@ export { dropMissing, type Gone, tooManyGone } from "./gone.js";
 export { type AuthVerdicts, HEADER_FIELDS, headersOf, type MailHeaders, mailHeadersOf } from "./headers.js";
 export { type MailIdsInput, mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
+export { type MailTurn, mailTurn } from "./owed.js";
 export { type Address, htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, type ParsedMail, parseMail, } from "./parse.js";
 export { PARTIAL, type PartialOutcome } from "./partial.js";
 export { PRESET_NAMES, PRESETS, type PresetName, presetMatches } from "./presets.js";
@@ -13,6 +14,7 @@ export { domainsToAge, groupKey, type Probe, type ProbeGroup, probeMail, SUGGEST
 export { type MailFolderProgress, mailProgress } from "./progress.js";
 export { ATTACHMENT_CHARS, attachmentsText, hitText, lowerSuspicious, type MailSearch, type ShownMail, searchMail, showMail, withAttachmentText, } from "./read.js";
 export { type FileStamp, FULL_PASS_MS, MBOX_RESUME, type MboxPoint, mergeRanges, parsePoint, type Ranges, type ResumePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
+export { isBulk, type MailReview, type MailReviewOptions, OWED_DAYS, REVIEW_THREADS, reviewMail } from "./review.js";
 export { ruleInput, STORE_ACTION } from "./rule-input.js";
 export { type MailRuleSet, storedMailRule, storedMailRuleSet, storedMailRules } from "./rule-stored.js";
 export { mapProposedTags, ruleTagger, settleRuleTags, type TagOutcome } from "./rule-tags.js";

package/dist/mail/index.js

@@ -6,6 +6,7 @@ export { dropMissing, tooManyGone } from "./gone.js";
 export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";
 export { mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
+export { mailTurn } from "./owed.js";
 export { htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, parseMail, } from "./parse.js";
 export { PARTIAL } from "./partial.js";
 export { PRESET_NAMES, PRESETS, presetMatches } from "./presets.js";
@@ -13,6 +14,7 @@ export { domainsToAge, groupKey, probeMail, SUGGEST_RULE } from "./probe.js";
 export { mailProgress } from "./progress.js";
 export { ATTACHMENT_CHARS, attachmentsText, hitText, lowerSuspicious, searchMail, showMail, withAttachmentText, } from "./read.js";
 export { FULL_PASS_MS, MBOX_RESUME, mergeRanges, parsePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
+export { isBulk, OWED_DAYS, REVIEW_THREADS, reviewMail } from "./review.js";
 export { ruleInput, STORE_ACTION } from "./rule-input.js";
 export { storedMailRule, storedMailRuleSet, storedMailRules } from "./rule-stored.js";
 export { mapProposedTags, ruleTagger, settleRuleTags } from "./rule-tags.js";

package/dist/mail/owed.d.ts

@@ -0,0 +1,11 @@
+import type { NewestEmail } from "../store/store.js";
+/** Whose turn a thread is: the owner owes an answer, waits for one, or neither. */
+export type MailTurn = "owed" | "waiting" | null;
+/**
+ * **The one place that says what the owner owes in mail** (`review --unanswered`, `--waiting`, `tasks agenda`).
+ * Owed: the newest email came in and names the owner in To or Cc. Mail sent to many, lists and envelopes count too
+ * (the owner's ruling: look at all mail); each item carries its marks instead, for the reader to sort. No question
+ * detection. Waiting: the owner wrote last. Mail answered from another client counts, since its copy in Sent or All
+ * Mail is synced.
+ */
+export declare const mailTurn: (newest: NewestEmail | null) => MailTurn;

package/dist/mail/owed.js

@@ -0,0 +1,14 @@
+/**
+ * **The one place that says what the owner owes in mail** (`review --unanswered`, `--waiting`, `tasks agenda`).
+ * Owed: the newest email came in and names the owner in To or Cc. Mail sent to many, lists and envelopes count too
+ * (the owner's ruling: look at all mail); each item carries its marks instead, for the reader to sort. No question
+ * detection. Waiting: the owner wrote last. Mail answered from another client counts, since its copy in Sent or All
+ * Mail is synced.
+ */
+export const mailTurn = (newest) => {
+    if (newest === null)
+        return null;
+    if (newest.outgoing)
+        return "waiting";
+    return newest.addressed ? "owed" : null;
+};

package/dist/mail/retry.js

@@ -1,6 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { mailAccountKey } from "./account-key.js";
 import { addressOf, FETCH_CHUNK, readAttachments } from "./attachments.js";
+import { sentAtOf } from "./email-input.js";
 import { mailFolders } from "./folders.js";
 import { mailHeadersOf } from "./headers.js";
 import { parseMail } from "./parse.js";
@@ -74,7 +75,7 @@ export const retryUnread = async ({ store, source, account, since, max, maxBodyC
                         to: mail.to.map(addressOf),
                         cc: mail.cc.map(addressOf),
                         bcc: mail.bcc.map(addressOf),
-                        sentAt: null,
+                        sentAt: sentAtOf(mail.date, item.receivedAt),
                         receivedAt: Date.parse(item.receivedAt),
                         bodyText: mail.text || null,
                         size: item.size ?? stored.size,

package/dist/mail/review.d.ts

@@ -0,0 +1,37 @@
+import { type Review, type ReviewChat } from "../domain/models.js";
+import type { AccountKey, EmailMarks, MessageStore, NewestEmail, StoredHit } from "../store/store.js";
+/** Every thread is a local read; this many keep one answer readable, and the rest wait in `skipped`. */
+export declare const REVIEW_THREADS = 50;
+/** Without a date, `--unanswered` and `--waiting` look as far back as `tasks agenda` does. */
+export declare const OWED_DAYS = 30;
+export interface MailReviewOptions {
+    /** ms: where a thread with no point of its own starts. */
+    since: number;
+    /** A thread's own start, by its external id. */
+    points?: ReadonlyMap<string, number>;
+    /** Leave out threads whose newest email is mail sent to many, a list's or an envelope (`bulk:false`). */
+    noBulk?: boolean;
+    /** Only threads the owner owes an answer for at least this many hours (`mailTurn`). */
+    unansweredAfterHours?: number;
+    /** Only threads where the owner wrote last and nobody answered for at least this many hours. */
+    waitingAfterHours?: number;
+    now?: number;
+}
+/** A review of mail: each thread a chat, each email a stored hit with its locator. */
+export type MailHit = StoredHit & {
+    marks?: EmailMarks;
+};
+export interface MailReview extends Review {
+    chats: (Omit<ReviewChat, "messages"> & {
+        messages: MailHit[];
+    })[];
+}
+/** Mail sent to many, a list's, or recorded by an envelope rule without its text. */
+export declare const isBulk: (email: NewestEmail) => boolean;
+/**
+ * **Every email, both sides, in each thread that changed since a point** — `review` over the store's mail, in
+ * messenger review's shape: a thread is a chat, an email a message. Reads the store alone, so it costs the mail
+ * server nothing; it opens no task (the owner reviews mail tasks first). Cut where sync proved the mailbox
+ * (`syncedThrough`), so the next review starting at `until` misses nothing sync had stored by then.
+ */
+export declare const reviewMail: (store: MessageStore, mailbox: AccountKey, options: MailReviewOptions) => Promise<MailReview>;

package/dist/mail/review.js

@@ -0,0 +1,118 @@
+import { CliError } from "@wirecat/cli-base";
+import { senderIsMe } from "../domain/models.js";
+import { mailTurn } from "./owed.js";
+/** Every thread is a local read; this many keep one answer readable, and the rest wait in `skipped`. */
+export const REVIEW_THREADS = 50;
+const REVIEW_PER_THREAD = 50;
+/** Without a date, `--unanswered` and `--waiting` look as far back as `tasks agenda` does. */
+export const OWED_DAYS = 30;
+// A thread is picked by its own time, which is the Date header where sync stored one; mail delivered up to a day
+// after its date is still found.
+const DATED_SLACK = 86_400_000;
+const HOUR = 3_600_000;
+/** Mail sent to many, a list's, or recorded by an envelope rule without its text. */
+export const isBulk = (email) => email.bulk || email.list || email.envelope;
+const absent = (error) => {
+    if (error instanceof CliError && error.code === "not_found")
+        return undefined;
+    throw error;
+};
+/**
+ * How far sync proved the mailbox: everything that arrived before `until` is stored. Review cuts there, so mail a
+ * running sync has not stored yet cannot slip behind a saved point.
+ */
+const syncedThrough = async (store, mailbox) => {
+    const saved = await store.sync.syncState(mailbox, "mail_coverage");
+    if (!saved)
+        return { until: undefined, complete: false };
+    try {
+        const { until, state } = JSON.parse(saved.value);
+        const at = typeof until === "string" ? Date.parse(until) : Number.NaN;
+        return { until: Number.isNaN(at) ? undefined : at, complete: state === "window" && !Number.isNaN(at) };
+    }
+    catch {
+        return { until: undefined, complete: false };
+    }
+};
+const wanted = (thread, { noBulk, unansweredAfterHours, waitingAfterHours }, now) => {
+    const newest = thread.newest;
+    if (unansweredAfterHours !== undefined || waitingAfterHours !== undefined) {
+        const turn = mailTurn(newest);
+        const age = newest === null ? 0 : now - newest.at;
+        const owed = turn === "owed" && unansweredAfterHours !== undefined && age >= unansweredAfterHours * HOUR;
+        const waiting = turn === "waiting" && waitingAfterHours !== undefined && age >= waitingAfterHours * HOUR;
+        if (!owed && !waiting)
+            return "no";
+    }
+    return noBulk && newest !== null && !newest.outgoing && isBulk(newest) ? "quiet" : "read";
+};
+/** The emails after the other side last wrote: what is owed, or what waits for an answer. */
+const turnTail = (messages, owner, ownerWrote) => {
+    const start = messages.findLastIndex((one) => senderIsMe(one, owner) !== ownerWrote);
+    return messages.slice(start + 1);
+};
+/**
+ * **Every email, both sides, in each thread that changed since a point** — `review` over the store's mail, in
+ * messenger review's shape: a thread is a chat, an email a message. Reads the store alone, so it costs the mail
+ * server nothing; it opens no task (the owner reviews mail tasks first). Cut where sync proved the mailbox
+ * (`syncedThrough`), so the next review starting at `until` misses nothing sync had stored by then.
+ */
+export const reviewMail = async (store, mailbox, options) => {
+    const { since, points } = options;
+    const now = options.now ?? Date.now();
+    const account = await store.accounts.storedAccount(mailbox).catch(absent);
+    const synced = account ? await syncedThrough(store, mailbox) : { until: undefined, complete: false };
+    const cut = Math.min(now, synced.until ?? now);
+    const startOf = (thread) => points?.get(thread) ?? since;
+    const activity = account ? await store.mail.threadActivity(account.id, since - DATED_SLACK) : [];
+    const changed = activity.filter((thread) => Math.max(thread.lastEmailAt, thread.newest?.at ?? 0) > startOf(thread.threadId));
+    const picked = changed.map((thread) => ({ thread, as: wanted(thread, options, now) }));
+    const shown = picked.filter(({ as }) => as === "read").map(({ thread }) => thread);
+    const read = shown.slice(0, REVIEW_THREADS);
+    const skipped = shown.slice(REVIEW_THREADS).map(({ threadId, subject, lastEmailAt }) => ({
+        id: threadId,
+        title: subject,
+        lastMessageAt: new Date(lastEmailAt).toISOString(),
+    }));
+    const turns = options.unansweredAfterHours !== undefined || options.waitingAfterHours !== undefined;
+    const chats = [];
+    const checked = {};
+    for (const thread of read) {
+        const hits = await store.mail.threadHits(account?.id ?? 0, thread.threadId, {
+            after: startOf(thread.threadId),
+            until: cut,
+        });
+        const tail = turns ? turnTail(hits, mailbox.account, thread.newest?.outgoing === true) : hits;
+        const marks = await store.mail.emailMarks(account?.id ?? 0, tail.map((hit) => hit.id));
+        const messages = tail.map((hit) => {
+            const mark = marks.get(hit.id);
+            return mark ? { ...hit, marks: mark } : hit;
+        });
+        const more = messages.length > REVIEW_PER_THREAD;
+        if (messages.length > 0)
+            chats.push({
+                id: thread.threadId,
+                title: thread.subject,
+                kind: "dialog",
+                messages: more ? messages.slice(-REVIEW_PER_THREAD) : messages,
+                more,
+            });
+        if (!more)
+            checked[thread.threadId] = new Date(cut).toISOString();
+    }
+    const earliest = changed.reduce((low, thread) => Math.min(low, startOf(thread.threadId)), Number.POSITIVE_INFINITY);
+    return {
+        since: new Date(points === undefined || changed.length === 0 ? since : earliest).toISOString(),
+        until: new Date(cut).toISOString(),
+        complete: synced.complete && skipped.length === 0 && chats.every((one) => !one.more),
+        chats,
+        skipped,
+        partial: false,
+        quiet: picked.filter(({ as }) => as === "quiet").length,
+        ...(options.unansweredAfterHours === undefined
+            ? {}
+            : { unanswered: { olderThanHours: options.unansweredAfterHours } }),
+        ...(options.waitingAfterHours === undefined ? {} : { waiting: { olderThanHours: options.waitingAfterHours } }),
+        ...(points === undefined ? {} : { checked }),
+    };
+};

package/dist/mail/sync.js

@@ -24,6 +24,8 @@ const DAY = 86_400_000;
 const EDGE = 2 * DAY;
 /** How often a long run saves where it is, so a kill costs at most this much listing again. */
 const SAVE_EVERY_MS = 30_000;
+/** About 55 runs clear a 276,000-email account; each is a short write that does not hold the sync up. */
+const SENT_AT_BACKFILL_PER_RUN = 5000;
 const SLICE_SIZE = 50;
 const SLICE_PAUSE_MS = 100;
 /** About a minute of listing; the 30-day window of the timer stays below it. */
@@ -682,7 +684,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                     // Subject and text stay out of the columns search reads, so recorded mail is never a search hit.
                     subject: null,
                     from: headers?.from === undefined ? null : { address: headers.from, name: headers.fromName ?? null },
-                    sentAt: null,
+                    sentAt: Date.parse(item.receivedAt),
                     receivedAt: Date.parse(item.receivedAt),
                     bodyText: null,
                     size: item.size ?? null,
@@ -816,6 +818,8 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         await store.mail.setMailboxes(accountId, [bulkBox], bulk, startedAt);
     if (!snapshot)
         await store.sync.setSyncState(key, "mail_folder_scope", scope);
+    if (!snapshot)
+        await store.mail.backfillSentAt(accountId, SENT_AT_BACKFILL_PER_RUN);
     await stopIfAborted();
     const indexed = await index?.(store, key);
     const coverage = {

package/dist/mail/testing/fake.d.ts

@@ -12,6 +12,8 @@ export interface FakeMail {
     from: FakePerson;
     to: FakePerson[];
     cc?: FakePerson[];
+    /** The Date header, when it differs from the server's internal date `receivedAt`. */
+    date?: string;
     text?: string;
     html?: string;
     listId?: string;

package/dist/mail/testing/fake.js

@@ -31,7 +31,7 @@ export const rawOf = (m) => {
         ...(m.listId ? [`List-Id: News <${m.listId}>`, `List-Unsubscribe: <mailto:leave@${m.listId}>`] : []),
         `Subject: ${m.subject}`,
         `Message-ID: <${m.messageId}@example.test>`,
-        `Date: ${new Date(m.receivedAt).toUTCString()}`,
+        `Date: ${m.date ?? new Date(m.receivedAt).toUTCString()}`,
         "MIME-Version: 1.0",
         ...(m.extraHeaders ?? []),
     ];

package/dist/services/agenda-mail.d.ts

@@ -0,0 +1,15 @@
+import { type MailTurn } from "../mail/owed.js";
+import { type AccountKey, type ChatActivity, type MessageStore, queryFilter } from "../store/store.js";
+import type { ChatCoverage } from "./chat-coverage.js";
+export interface TurnActivity extends ChatActivity {
+    turn: MailTurn;
+}
+/**
+ * `tasks agenda` over an email account: each thread with mail in the window, its newest email deciding whose turn it
+ * is (`mailTurn`). `storedAt` is when sync last proved the mailbox, so a quiet day with no mail is not `stale`.
+ */
+export declare const mailActivity: (store: MessageStore, account: AccountKey, since: number, chats: Parameters<typeof queryFilter>[0] | undefined) => Promise<{
+    chats: TurnActivity[];
+    storedAt: string | null;
+    coverage: (ids: string[]) => ChatCoverage[];
+}>;

package/dist/services/agenda-mail.js

@@ -0,0 +1,66 @@
+import { CliError } from "@wirecat/cli-base";
+import { mailTurn } from "../mail/owed.js";
+import { MAIL_AGENDA_COLUMNS, queryFilter, } from "../store/store.js";
+const absent = (error) => {
+    if (error instanceof CliError && error.code === "not_found")
+        return undefined;
+    throw error;
+};
+/**
+ * `tasks agenda` over an email account: each thread with mail in the window, its newest email deciding whose turn it
+ * is (`mailTurn`). `storedAt` is when sync last proved the mailbox, so a quiet day with no mail is not `stale`.
+ */
+export const mailActivity = async (store, account, since, chats) => {
+    const stored = await store.accounts.storedAccount(account).catch(absent);
+    if (!stored)
+        return { chats: [], storedAt: null, coverage: () => [] };
+    const where = chats
+        ? queryFilter(chats, MAIL_AGENDA_COLUMNS, { command: "tasks agenda" })
+        : undefined;
+    const threads = await store.mail.threadActivity(stored.id, since, where);
+    const synced = await store.sync.syncState(account, "mail_coverage");
+    const window = (() => {
+        try {
+            return JSON.parse(synced?.value ?? "{}");
+        }
+        catch {
+            return {};
+        }
+    })();
+    const byId = new Map(threads.map((thread) => [thread.threadId, thread]));
+    return {
+        chats: threads.map((thread) => ({
+            chatId: thread.threadId,
+            title: thread.subject,
+            kind: "dialog",
+            lastMessageAt: new Date(thread.newest?.at ?? thread.lastEmailAt).toISOString(),
+            lastMessageId: thread.newest?.externalId ?? null,
+            lastFromOwner: thread.newest ? thread.newest.outgoing : null,
+            turn: mailTurn(thread.newest),
+        })),
+        storedAt: synced?.at ?? null,
+        coverage: (ids) => ids.map((chatId) => {
+            const thread = byId.get(chatId);
+            const newest = thread?.newest?.at ?? thread?.lastEmailAt;
+            const until = window.until === undefined ? Number.NaN : Date.parse(window.until);
+            return {
+                chatId,
+                title: thread?.subject ?? null,
+                completeness: {
+                    chatId,
+                    // Sync holds a window of the mailbox, never a thread's whole history.
+                    state: synced ? "partial" : "unknown",
+                    upToDate: window.state === "window" && newest !== undefined && !Number.isNaN(until) ? newest <= until : null,
+                    gaps: false,
+                    reachesStart: false,
+                    fetchedAt: synced?.at ?? null,
+                },
+                held: {
+                    messages: thread?.emails ?? 0,
+                    oldestAt: null,
+                    newestAt: newest === undefined ? null : new Date(newest).toISOString(),
+                },
+            };
+        }),
+    };
+};

package/dist/services/agenda.d.ts

@@ -79,6 +79,10 @@ export interface Agenda {
 export interface AgendaService {
     show(options?: AgendaOptions): Promise<Agenda>;
 }
+/**
+ * An email account's chats are its threads, and whose turn one is follows `mailTurn` (`../mail/owed.ts`), not merely
+ * who wrote last: mail sent to many is never owed.
+ */
 export declare const agendaService: (deps: ServiceDeps, now?: () => number) => AgendaService;
 export type AgendaItem = v.InferOutput<typeof agenda>;
 /** The agenda in entity keys, as `--json` and MCP answer it; chats become `chat:` references. */