@wirecat/cli-core 0.574.0 → 0.576.0

package/dist/mail/cli/review.js

@@ -19,6 +19,7 @@ import { formatReference } from "../../domain/references.js";
 import { AGENDA_DEFAULTS } from "../../services/agenda.js";
 import { REVIEW_DAYS, reviewStart } from "../../services/inbox.js";
 import { readPastMark } from "../marks.js";
+import { BULK_TRIAGE_DEFAULTS } from "../newsletter.js";
 import { hitText } from "../read.js";
 import { OWED_DAYS, REVIEW_THREADS, reviewMail } from "../review.js";
 const DAY = 86_400_000;
@@ -74,9 +75,10 @@ const waitingHours = (value) => value === true ? AGENDA_DEFAULTS.waiting / 3_600
 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 markText = (marks, excerptOnly = false) => {
     const said = [
-        marks?.bulk ? "bulk" : "",
+        marks?.bulk || excerptOnly ? "bulk" : "",
+        excerptOnly ? "excerpt only" : "",
         marks?.listId ? `list ${marks.listId}` : "",
         marks?.ruleId ? `rule ${marks.ruleId}` : "",
     ];
@@ -84,9 +86,11 @@ const markText = (marks) => {
     return shown ? `\n  [${shown}]` : "";
 };
 const reviewAnswer = (found, mailbox, fresh, step) => {
+    // Excerpts come after the mail written to the owner, so an agent with a budget reads that first.
     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));
+        .sort((a, b) => Number(a.excerptOnly ?? false) - Number(b.excerptOnly ?? false) ||
+        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;
@@ -126,7 +130,8 @@ const reviewAnswer = (found, mailbox, fresh, step) => {
             ...summaryOf(message, mailbox),
             email: {
                 ...messageItem(message, mailbox).email,
-                bulk: message.marks?.bulk ?? false,
+                bulk: (message.marks?.bulk ?? false) || message.excerptOnly === true,
+                ...(message.excerptOnly ? { excerpt_only: true } : {}),
                 list_id: message.marks?.listId ?? null,
                 rule_id: message.marks?.ruleId ?? null,
                 ...(message.marks
@@ -150,16 +155,22 @@ const holderReview = async (command, mail, holder, query) => {
     const { unanswered, waiting } = command.opts();
     if (typedQuery(query).trim() || unanswered !== undefined || waiting !== undefined)
         throw new CliError("validation_error", "--holder reads past its own mark — not with a query, --unanswered or --waiting");
+    const triage = mail.bulkTriage?.(command) ?? BULK_TRIAGE_DEFAULTS;
     const { read, mailbox, marks } = await mail.read(command, async (store, mailbox) => {
-        const read = await readPastMark(store, mailbox, holder);
-        const account = read.emails.length ? await store.accounts.storedAccount(mailbox) : undefined;
-        const marks = account
-            ? await store.mail.emailMarks(account.id, read.emails.map((one) => one.id))
-            : new Map();
+        const read = await readPastMark(store, mailbox, holder, { triage });
+        const ids = [...read.emails, ...read.excerpts.map(({ email }) => email)].map((one) => one.id);
+        const account = ids.length ? await store.accounts.storedAccount(mailbox) : undefined;
+        const marks = account ? await store.mail.emailMarks(account.id, ids) : new Map();
         return { read, mailbox, marks };
     });
     // An agent reads this: earlier mail and signatures stay out of its text; the fingerprint is over the stored body.
-    const emails = read.emails.map((email) => ({ ...email, text: mailOwnText(email.text) }));
+    const emails = [
+        ...read.emails.map((email) => ({ ...email, text: mailOwnText(email.text) })),
+        ...read.excerpts.map(({ email, excerpt }) => {
+            const subject = email.email?.subject;
+            return { ...email, text: subject ? `${subject}\n\n${excerpt}` : excerpt, excerptOnly: true };
+        }),
+    ];
     const chats = new Map();
     for (const email of emails) {
         const chat = chats.get(email.chatId) ?? {
@@ -193,13 +204,22 @@ const holderReview = async (command, mail, holder, query) => {
         ...(skipped.length
             ? [{ field: "items", why: `left out: ${skipped.map(([reason, count]) => `${count} ${reason}`).join(", ")}` }]
             : []),
+        ...(read.excerpts.length
+            ? [
+                {
+                    field: "items",
+                    why: `${read.excerpts.length} bulk emails (excerpt_only) as their subject and first lines: ` +
+                        "read one whole with `messages show <ref>` when it is an order, an invoice or a request",
+                },
+            ]
+            : []),
     ];
     const output = outputFor(command);
     renderAnswer(command, output, answer, () => {
         output.renderer.note(read.mark
             ? `${holder}: past ${read.mark.throughId}; acknowledge with --cursor ${read.cursor}${read.more ? "; more after these" : ""}`
             : `${holder} has no mark yet: it starts from now — acknowledge with --cursor ${read.cursor}`);
-        return emails.map((hit) => `${hitText(hit)}${markText(marks.get(hit.id))}\n`).join("");
+        return emails.map((hit) => `${hitText(hit)}${markText(marks.get(hit.id), hit.excerptOnly)}\n`).join("");
     });
 };
 /**
@@ -225,8 +245,9 @@ export const mailReviewCommand = (mail) => annotate(new Command("review"), {
     .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("--holder <name>", "read for this holder — an agent or a pipeline — what is stored past its processing mark, by store order; " +
-    "bulk, envelopes, drafts, suspicious senders and partial mail left out; each text without quoted earlier mail " +
-    "or the signature; `messages acknowledge` moves the mark")
+    "newsletters, envelopes, drafts, suspicious senders and partial mail left out; other bulk mail after the rest, " +
+    "as its subject and first lines (excerpt_only); each text without quoted earlier mail or the signature; " +
+    "`messages acknowledge` moves the mark")
     .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.

package/dist/mail/findings.d.ts

@@ -1,4 +1,6 @@
+import { INVOICE_DIRECTIONS, MONEY_DIRECTIONS } from "../domain/finance.js";
 import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.js";
+import { ORDER_PURPOSES, ORDER_STATUSES } from "../domain/orders.js";
 import { type FactFinding, type FindingEvidence, type TaskFinding } from "../meetings/index.js";
 export { MAIL_FINDINGS_KIND } from "../store/mail-findings.js";
 /** At most this many findings in one run's batch, and per sender in it. */
@@ -39,7 +41,77 @@ export interface MailNewContactFinding extends Cited {
     name: string;
     reason?: string;
 }
-export type MailFinding = MailTaskFinding | MailFactFinding | MailTaskUpdateFinding | MailMemoryFinding | MailLinkFinding | MailNewContactFinding;
+/** An invoice the mail carries; accepting it records the invoice through `store.finance`, confirmed. */
+export interface MailInvoiceFinding extends Cited {
+    kind: "invoice";
+    direction: (typeof INVOICE_DIRECTIONS)[number];
+    /** `person:` or `organization:`. */
+    counterparty: string;
+    currency: string;
+    lines: {
+        description: string;
+        quantity?: string;
+        unitPrice?: string;
+        amount?: string;
+    }[];
+    /** The total printed on it: the store refuses it unless it is the lines' sum. */
+    total?: string;
+    number?: string;
+    issueDate?: string;
+    dueDate?: string;
+    project?: string;
+    reason: string;
+}
+/** A payment the mail confirms, such as a receipt; accepting it records the payment through `store.finance`. */
+export interface MailPaymentFinding extends Cited {
+    kind: "payment";
+    direction: (typeof MONEY_DIRECTIONS)[number];
+    payer?: string;
+    payee?: string;
+    amount: string;
+    currency: string;
+    /** `YYYY-MM-DD`. */
+    date: string;
+    /** The payment's own reference text, such as the receipt number. */
+    reference?: string;
+    /** Stored invoices it settles, in the payment's currency. */
+    allocations?: {
+        invoice: string;
+        amount: string;
+    }[];
+    project?: string;
+    reason: string;
+}
+/** An order the mail confirms; accepting it records the order through `store.orders`. */
+export interface MailOrderFinding extends Cited {
+    kind: "order";
+    purpose: (typeof ORDER_PURPOSES)[number];
+    /** Whom it is for; the owner when left out. */
+    customer?: string;
+    supplier?: string;
+    supplierName: string;
+    number?: string;
+    total?: string;
+    currency?: string;
+    status?: (typeof ORDER_STATUSES)[number];
+    orderDate?: string;
+    fulfilledDate?: string;
+    invoice?: string;
+    payment?: string;
+    project?: string;
+    reason: string;
+}
+/** A later mail about a stored order, found by its shop and number: shipped, delivered, cancelled, returned. */
+export interface MailOrderUpdateFinding extends Cited {
+    kind: "order_update";
+    supplierName: string;
+    number: string;
+    status: (typeof ORDER_STATUSES)[number];
+    /** `YYYY-MM-DD`, the delivery day of a delivered order. */
+    date?: string;
+    reason: string;
+}
+export type MailFinding = MailTaskFinding | MailFactFinding | MailTaskUpdateFinding | MailMemoryFinding | MailLinkFinding | MailNewContactFinding | MailInvoiceFinding | MailPaymentFinding | MailOrderFinding | MailOrderUpdateFinding;
 export interface MailFindingsInput {
     schemaVersion: 1;
     /** `<holder>:<through_id>`: one batch per run of a holder over the mail it was given. */

package/dist/mail/findings.js

@@ -1,6 +1,8 @@
 import { CliError } from "@wirecat/cli-base";
+import { INVOICE_DIRECTIONS, MONEY_DIRECTIONS } from "../domain/finance.js";
 import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.js";
 import { formatLocator, parseLocator } from "../domain/locator.js";
+import { ORDER_PURPOSES, ORDER_STATUSES } from "../domain/orders.js";
 import { parseReference } from "../domain/references.js";
 import { findingFields, findingHash, findingId, findingText, meetingTimestamp, validateBatch, validateFinding, validEvidence, } from "../meetings/index.js";
 export { MAIL_FINDINGS_KIND } from "../store/mail-findings.js";
@@ -42,6 +44,18 @@ const LINKS = {
     "chat:email": "project",
 };
 const ADDRESS = /^[^\s@<>]+@[^\s@<>]+$/;
+const PARTY = /^(person|organization):[1-9]\d*$/;
+const INVOICE = /^invoice:[1-9]\d*$/;
+const PAYMENT = /^payment:[1-9]\d*$/;
+const PROJECT = /^project:[1-9]\d*$/;
+const oneOf = (value, allowed, what) => {
+    if (typeof value !== "string" || !allowed.includes(value))
+        return invalid(`${what} is ${allowed.join(", ")}`);
+    return value;
+};
+/** Money and dates stay text here: the store's finance and order services check them as they check the owner's. */
+const word = (value, limit) => findingText(value, limit);
+const optional = (key, value, read) => (value === undefined ? {} : { [key]: read(value) });
 const one = (raw, ids) => {
     if (!raw || typeof raw !== "object")
         return invalid("a finding is an object");
@@ -123,8 +137,157 @@ const one = (raw, ids) => {
                 evidence,
             };
         }
+        case "invoice": {
+            findingFields(raw, [
+                "id",
+                "kind",
+                "direction",
+                "counterparty",
+                "currency",
+                "lines",
+                "total",
+                "number",
+                "issueDate",
+                "dueDate",
+                "project",
+                "reason",
+                "evidence",
+            ], RULES.singular);
+            if (!Array.isArray(raw.lines) || raw.lines.length < 1 || raw.lines.length > 50)
+                return invalid("an invoice finding has 1–50 lines");
+            const lines = raw.lines.map((line) => {
+                if (!line || typeof line !== "object")
+                    return invalid("an invoice line is an object");
+                const fields = line;
+                findingFields(fields, ["description", "quantity", "unitPrice", "amount"], "invoice line");
+                return {
+                    description: word(fields.description, 500),
+                    ...optional("quantity", fields.quantity, (value) => word(value, 20)),
+                    ...optional("unitPrice", fields.unitPrice, (value) => word(value, 30)),
+                    ...optional("amount", fields.amount, (value) => word(value, 30)),
+                };
+            });
+            return {
+                id,
+                kind: "invoice",
+                direction: oneOf(raw.direction, INVOICE_DIRECTIONS, "an invoice's direction"),
+                counterparty: reference(raw.counterparty, PARTY, "an invoice's counterparty"),
+                currency: word(raw.currency, 3),
+                lines,
+                ...optional("total", raw.total, (value) => word(value, 30)),
+                ...optional("number", raw.number, (value) => word(value, 80)),
+                ...optional("issueDate", raw.issueDate, (value) => word(value, 10)),
+                ...optional("dueDate", raw.dueDate, (value) => word(value, 10)),
+                ...optional("project", raw.project, (value) => reference(value, PROJECT, "a project")),
+                reason: findingText(raw.reason, 2000),
+                evidence,
+            };
+        }
+        case "payment": {
+            findingFields(raw, [
+                "id",
+                "kind",
+                "direction",
+                "payer",
+                "payee",
+                "amount",
+                "currency",
+                "date",
+                "reference",
+                "allocations",
+                "project",
+                "reason",
+                "evidence",
+            ], RULES.singular);
+            let allocations;
+            if (raw.allocations !== undefined) {
+                if (!Array.isArray(raw.allocations) || raw.allocations.length < 1 || raw.allocations.length > 8)
+                    return invalid("a payment finding's allocations are 1–8 invoices it settles");
+                allocations = raw.allocations.map((share) => {
+                    if (!share || typeof share !== "object")
+                        return invalid("an allocation is an invoice and an amount");
+                    const fields = share;
+                    findingFields(fields, ["invoice", "amount"], "allocation");
+                    return {
+                        invoice: reference(fields.invoice, INVOICE, "an allocation's invoice"),
+                        amount: word(fields.amount, 30),
+                    };
+                });
+            }
+            return {
+                id,
+                kind: "payment",
+                direction: oneOf(raw.direction, MONEY_DIRECTIONS, "a payment's direction"),
+                ...optional("payer", raw.payer, (value) => reference(value, PARTY, "a payment's payer")),
+                ...optional("payee", raw.payee, (value) => reference(value, PARTY, "a payment's payee")),
+                amount: word(raw.amount, 30),
+                currency: word(raw.currency, 3),
+                date: word(raw.date, 10),
+                ...optional("reference", raw.reference, (value) => word(value, 500)),
+                ...(allocations === undefined ? {} : { allocations }),
+                ...optional("project", raw.project, (value) => reference(value, PROJECT, "a project")),
+                reason: findingText(raw.reason, 2000),
+                evidence,
+            };
+        }
+        case "order": {
+            findingFields(raw, [
+                "id",
+                "kind",
+                "purpose",
+                "customer",
+                "supplier",
+                "supplierName",
+                "number",
+                "total",
+                "currency",
+                "status",
+                "orderDate",
+                "fulfilledDate",
+                "invoice",
+                "payment",
+                "project",
+                "reason",
+                "evidence",
+            ], RULES.singular);
+            return {
+                id,
+                kind: "order",
+                purpose: oneOf(raw.purpose, ORDER_PURPOSES, "an order's purpose"),
+                ...optional("customer", raw.customer, (value) => reference(value, PARTY, "an order's customer")),
+                ...optional("supplier", raw.supplier, (value) => reference(value, PARTY, "an order's supplier")),
+                supplierName: word(raw.supplierName, 200),
+                ...optional("number", raw.number, (value) => word(value, 80)),
+                ...optional("total", raw.total, (value) => word(value, 30)),
+                ...optional("currency", raw.currency, (value) => word(value, 3)),
+                ...optional("status", raw.status, (value) => oneOf(value, ORDER_STATUSES, "an order's status")),
+                ...optional("orderDate", raw.orderDate, (value) => word(value, 10)),
+                ...optional("fulfilledDate", raw.fulfilledDate, (value) => word(value, 10)),
+                ...optional("invoice", raw.invoice, (value) => reference(value, INVOICE, "an order's invoice")),
+                ...optional("payment", raw.payment, (value) => reference(value, PAYMENT, "an order's payment")),
+                ...optional("project", raw.project, (value) => reference(value, PROJECT, "a project")),
+                reason: findingText(raw.reason, 2000),
+                evidence,
+            };
+        }
+        case "order_update": {
+            findingFields(raw, ["id", "kind", "supplierName", "number", "status", "date", "reason", "evidence"], RULES.singular);
+            const status = oneOf(raw.status, ORDER_STATUSES, "an order update's status");
+            if (raw.date !== undefined && status !== "delivered")
+                return invalid("only a delivered order update gives date");
+            return {
+                id,
+                kind: "order_update",
+                supplierName: word(raw.supplierName, 200),
+                number: word(raw.number, 80),
+                status,
+                ...optional("date", raw.date, (value) => word(value, 10)),
+                reason: findingText(raw.reason, 2000),
+                evidence,
+            };
+        }
         default:
-            return invalid("a mail finding is a task, task_update, fact, memory, link or new_contact");
+            return invalid("a mail finding is a task, task_update, fact, memory, link, new_contact, invoice, payment, order or order_update");
     }
 };
 /**

package/dist/mail/index.d.ts

@@ -9,7 +9,8 @@ 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 { acknowledgeMark, advancePastSkipped, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, type MailMark, type MailWaiting, type MarkRead, mailWaiting, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.js";
+export { acknowledgeMark, advancePastSkipped, type BulkExcerpt, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, type MailMark, type MailWaiting, type MarkRead, mailWaiting, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.js";
+export { BULK_TRIAGE_DEFAULTS, type BulkSorted, type BulkTriage, excerptOf, NEWSLETTER_DEFAULTS, NEWSLETTER_SENDERS, NEWSLETTER_WORDS, type NewsletterCues, newsletterSorter, ORDER_WORDS, } from "./newsletter.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";

package/dist/mail/index.js

@@ -10,6 +10,7 @@ export { HEADER_FIELDS, headersOf, mailHeadersOf } from "./headers.js";
 export { mailIds } from "./ids.js";
 export { decodedLabelName, decodeMailboxName, labelName, systemLabel } from "./labels.js";
 export { acknowledgeMark, advancePastSkipped, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, mailWaiting, markOf, marksOf, readPastMark, } from "./marks.js";
+export { BULK_TRIAGE_DEFAULTS, excerptOf, NEWSLETTER_DEFAULTS, NEWSLETTER_SENDERS, NEWSLETTER_WORDS, newsletterSorter, ORDER_WORDS, } from "./newsletter.js";
 export { mailTurn } from "./owed.js";
 export { htmlToText, looksLikeHtml, MAX_ATTACHMENTS, MAX_BODY_CHARS, parseMail, } from "./parse.js";
 export { PARTIAL } from "./partial.js";

package/dist/mail/marks.d.ts

@@ -1,11 +1,12 @@
 import type { AccountKey, MessageStore, StoredHit } from "../store/store.js";
+import { type BulkTriage } from "./newsletter.js";
 /** A holder's name: what `--holder` takes and the mark's key ends with. */
 export declare const HOLDER: RegExp;
 /** At most this many emails are read past the mark in one go; the rest come with the next read. */
 export declare const MARK_BATCH = 200;
 /** A partial email waits this long to be stored whole, then is skipped. */
 export declare const HOLD_PARTIAL_MS: number;
-export type SkipReason = "bulk" | "envelope" | "partial" | "draft" | "suspicious";
+export type SkipReason = "bulk" | "newsletter" | "envelope" | "partial" | "draft" | "suspicious";
 /**
  * How far one holder — an agent, a pipeline — has processed an account's mail, in the shared store (`sync_cursors`,
  * key `consumer:<holder>`). It counts by the store's insert order (`emails.id`), so mail stored late, older than what
@@ -29,9 +30,19 @@ export declare const markOf: (store: MessageStore, mailbox: AccountKey, holder:
 export declare const marksOf: (store: MessageStore, mailbox: AccountKey) => Promise<MailMark[]>;
 /** The mark's state, as a cursor `acknowledge` takes back: the last id read, and when it was read. */
 export declare const cursorOf: (throughId: number, readAt: number) => string;
+/** A bulk email that is not surely a newsletter: the holder gets its subject and first lines only. */
+export interface BulkExcerpt {
+    email: StoredHit;
+    /** The first lines of its own text, without the subject. */
+    excerpt: string;
+    /** What kept it, or the newsletter signs too few to leave it out. */
+    cues: string[];
+}
 export interface MarkRead {
     /** The emails for the holder, oldest first; bulk, envelopes, drafts, suspicious senders and partial mail left out. */
     emails: StoredHit[];
+    /** Bulk mail past the mark that is not surely a newsletter, oldest first; none when the triage gives no excerpts. */
+    excerpts: BulkExcerpt[];
     /** What `acknowledge --cursor` takes once the holder is done with these. */
     cursor: string;
     /** More is stored after this batch: read again after acknowledging. */
@@ -49,6 +60,7 @@ export interface MarkRead {
 export declare const readPastMark: (store: MessageStore, mailbox: AccountKey, holder: string, options?: {
     now?: number;
     limit?: number;
+    triage?: BulkTriage;
 }) => Promise<MarkRead>;
 /** Mail past a holder's marks that would reach it: how many emails, and when the oldest of them was stored. */
 export interface MailWaiting {
@@ -60,17 +72,17 @@ export interface MailWaiting {
 }
 /**
  * What waits for the holder in every stored mailbox, read only: what a schedule asks before it starts the holder's
- * agent, so a run with nothing new costs no model call. Bulk, envelopes, drafts, suspicious senders and partial mail
- * do not count.
+ * agent, so a run with nothing new costs no model call. Newsletters, envelopes, drafts, suspicious senders and partial
+ * mail do not count; other bulk mail counts as the excerpt the holder gets, unless the triage gives none.
  */
-export declare const mailWaiting: (store: MessageStore, holder: string, now?: number) => Promise<MailWaiting>;
+export declare const mailWaiting: (store: MessageStore, holder: string, now?: number, triage?: BulkTriage) => Promise<MailWaiting>;
 /**
- * Moves the holder's mark, in every stored mailbox, over the mail at its head that it would only skip — bulk,
- * envelopes, drafts, suspicious senders — as the agent would have acknowledged it, so a quiet holder's next check
+ * Moves the holder's mark, in every stored mailbox, over the mail at its head that it would only skip — newsletters,
+ * bulk mail the triage gives no excerpt of, envelopes, drafts, suspicious senders — as the agent would have acknowledged it, so a quiet holder's next check
  * does not read it all again. Suspicious senders' emails stay on the mark to be offered again. It stops at the first
  * email the holder reads. A store busy with a sync is left alone: the next check moves it.
  */
-export declare const advancePastSkipped: (store: MessageStore, holder: string, now?: number) => Promise<void>;
+export declare const advancePastSkipped: (store: MessageStore, holder: string, now?: number, triage?: BulkTriage) => Promise<void>;
 /**
  * Moves the holder's mark to the cursor its read gave, never back. An email whole when it was read counts read; one
  * still partial, or changed after the read (it may have become whole since), is held and comes with the next read.

package/dist/mail/marks.js

@@ -1,5 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
+import { mailOwnText } from "../conversations/mail-text.js";
 import { isBusy } from "../store/sqlite/transaction.js";
+import { BULK_TRIAGE_DEFAULTS, newsletterSorter } from "./newsletter.js";
 /** A holder's name: what `--holder` takes and the mark's key ends with. */
 export const HOLDER = /^[a-z0-9][a-z0-9-]{0,39}$/;
 /** At most this many emails are read past the mark in one go; the rest come with the next read. */
@@ -11,7 +13,14 @@ const MOST_HELD = 500;
 /** A cursor read at most this far in the future is a clock apart, not a forgery. */
 const CLOCK_SLACK_MS = 60_000;
 const PREFIX = "consumer:";
-const noneSkipped = () => ({ bulk: 0, envelope: 0, partial: 0, draft: 0, suspicious: 0 });
+const noneSkipped = () => ({
+    bulk: 0,
+    newsletter: 0,
+    envelope: 0,
+    partial: 0,
+    draft: 0,
+    suspicious: 0,
+});
 const keyOf = (holder) => {
     if (!HOLDER.test(holder))
         throw new CliError("validation_error", `a holder is lower-case letters, digits and dashes, not "${holder}"`);
@@ -83,14 +92,54 @@ const parseCursor = (cursor) => {
  * empty and gives the cursor of the newest stored email.
  */
 export const readPastMark = async (store, mailbox, holder, options = {}) => {
-    const { wanted, oldestStoredAt: _, ...read } = await examine(store, mailbox, holder, options);
-    return { emails: await store.mail.emailHits(wanted), ...read };
+    const { wanted, sorted, oldestStoredAt: _, ...read } = await examine(store, mailbox, holder, options);
+    const excerpts = wanted.flatMap((id) => {
+        const one = sorted.get(id);
+        return one ? [{ email: one.email, excerpt: one.excerpt, cues: one.cues }] : [];
+    });
+    const emails = await store.mail.emailHits(wanted.filter((id) => !sorted.has(id)));
+    return { emails, excerpts, ...read };
+};
+/**
+ * The batch's bulk emails a holder might read, sorted by `newsletterSorter`, and where the batch ends so it holds at
+ * most `perRead` excerpts. Drafts, envelopes, suspicious senders and partial mail keep their own verdicts.
+ */
+const sortBulk = async (store, batch, triage) => {
+    const sorted = new Map();
+    if (!triage.excerpts)
+        return { sorted, end: batch.length };
+    const sort = newsletterSorter(triage.cues);
+    let excerpts = 0;
+    for (const [index, marked] of batch.entries()) {
+        if (!marked.bulk || marked.draft || marked.envelope || marked.demoted || marked.partial)
+            continue;
+        const [email] = await store.mail.emailHits([marked.id]);
+        if (!email)
+            continue;
+        const subject = email.email?.subject ?? null;
+        const body = subject && email.text.startsWith(`${subject}\n\n`) ? email.text.slice(subject.length + 2) : email.text;
+        const one = sort({ subject, text: mailOwnText(body), from: email.email?.from?.address ?? null });
+        if (one.verdict === "excerpt" && excerpts === triage.perRead)
+            return { sorted, end: index };
+        if (one.verdict === "excerpt")
+            excerpts += 1;
+        sorted.set(marked.id, { ...one, email });
+    }
+    return { sorted, end: batch.length };
 };
-/** `readPastMark` without the emails' text: the store ids it would read, by their verdicts. */
-const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_BATCH, after }) => {
+/** `readPastMark` before it reads the emails: the store ids it would read by their verdicts, and the bulk sorted. */
+const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_BATCH, after, triage = BULK_TRIAGE_DEFAULTS, }) => {
     const saved = await markOf(store, mailbox, holder);
     const account = await accountOf(store, mailbox);
-    const empty = { wanted: [], oldestStoredAt: null, more: false, held: 0, skipped: noneSkipped(), mark: saved };
+    const empty = {
+        wanted: [],
+        sorted: new Map(),
+        oldestStoredAt: null,
+        more: false,
+        held: 0,
+        skipped: noneSkipped(),
+        mark: saved,
+    };
     if (!account)
         return { ...empty, cursor: cursorOf(0, now) };
     if (!saved)
@@ -103,7 +152,8 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
     const newer = found.filter((email) => email.id > mark.throughId);
     const unsettled = newer.findIndex((email) => email.storedAt > settledAt);
     const fresh = unsettled === -1 ? newer : newer.slice(0, unsettled);
-    const batch = fresh.slice(0, limit);
+    const { sorted, end } = await sortBulk(store, fresh.slice(0, limit), triage);
+    const batch = fresh.slice(0, end);
     const examined = [...found.filter((email) => email.id <= mark.throughId), ...batch];
     const skipped = noneSkipped();
     const wanted = [];
@@ -111,7 +161,12 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
     let held = 0;
     for (const email of examined) {
         const said = verdict(email, now);
-        if (said === "read") {
+        const bulk = sorted.get(email.id);
+        if (bulk?.verdict === "newsletter") {
+            if (email.id > mark.throughId)
+                skipped.newsletter += 1;
+        }
+        else if (said === "read" || bulk) {
             wanted.push(email.id);
             oldestStoredAt = Math.min(oldestStoredAt ?? email.storedAt, email.storedAt);
         }
@@ -122,6 +177,7 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
     }
     return {
         wanted: wanted.sort((a, b) => a - b),
+        sorted: new Map([...sorted].filter(([, one]) => one.verdict === "excerpt")),
         oldestStoredAt,
         cursor: cursorOf(batch.at(-1)?.id ?? mark.throughId, now),
         more: newer.length > batch.length,
@@ -132,17 +188,17 @@ const examine = async (store, mailbox, holder, { now = Date.now(), limit = MARK_
 };
 /**
  * What waits for the holder in every stored mailbox, read only: what a schedule asks before it starts the holder's
- * agent, so a run with nothing new costs no model call. Bulk, envelopes, drafts, suspicious senders and partial mail
- * do not count.
+ * agent, so a run with nothing new costs no model call. Newsletters, envelopes, drafts, suspicious senders and partial
+ * mail do not count; other bulk mail counts as the excerpt the holder gets, unless the triage gives none.
  */
-export const mailWaiting = async (store, holder, now = Date.now()) => {
+export const mailWaiting = async (store, holder, now = Date.now(), triage = BULK_TRIAGE_DEFAULTS) => {
     const waiting = { unmarked: false, emails: 0, oldestStoredAt: null };
     for (const mailbox of await store.accounts.accounts()) {
         if (mailbox.provider !== "email")
             continue;
         let after;
         for (;;) {
-            const read = await examine(store, mailbox, holder, { now, ...(after === undefined ? {} : { after }) });
+            const read = await examine(store, mailbox, holder, { now, triage, ...(after === undefined ? {} : { after }) });
             if (!read.mark) {
                 waiting.unmarked = true;
                 break;
@@ -159,17 +215,17 @@ export const mailWaiting = async (store, holder, now = Date.now()) => {
     return waiting;
 };
 /**
- * Moves the holder's mark, in every stored mailbox, over the mail at its head that it would only skip — bulk,
- * envelopes, drafts, suspicious senders — as the agent would have acknowledged it, so a quiet holder's next check
+ * Moves the holder's mark, in every stored mailbox, over the mail at its head that it would only skip — newsletters,
+ * bulk mail the triage gives no excerpt of, envelopes, drafts, suspicious senders — as the agent would have acknowledged it, so a quiet holder's next check
  * does not read it all again. Suspicious senders' emails stay on the mark to be offered again. It stops at the first
  * email the holder reads. A store busy with a sync is left alone: the next check moves it.
  */
-export const advancePastSkipped = async (store, holder, now = Date.now()) => {
+export const advancePastSkipped = async (store, holder, now = Date.now(), triage = BULK_TRIAGE_DEFAULTS) => {
     for (const mailbox of await store.accounts.accounts()) {
         if (mailbox.provider !== "email")
             continue;
         for (;;) {
-            const read = await examine(store, mailbox, holder, { now });
+            const read = await examine(store, mailbox, holder, { now, triage });
             if (!read.mark || read.wanted.length > 0 || read.cursor === cursorOf(read.mark.throughId, now))
                 break;
             try {