@wirecat/cli-core 0.559.0 → 0.560.0

package/dist/entities/mail-findings.js

@@ -0,0 +1,68 @@
+import * as v from "valibot";
+import { FACT_TYPES, MEMORY_KINDS, MEMORY_SCOPES, WORK_TASK_TYPES } from "../domain/knowledge.js";
+import { author, id, reference, text, time } from "./fields.js";
+const evidence = v.strictObject({ reference, fingerprint: text });
+const base = { id, evidence: v.array(evidence) };
+const finding = v.variant("kind", [
+    v.strictObject({
+        ...base,
+        kind: v.literal("task"),
+        project: v.optional(reference),
+        type: v.picklist(WORK_TASK_TYPES),
+        title: text,
+        reason: text,
+        commitment: v.picklist(["explicit", "inferred"]),
+        due_at: v.optional(time),
+        due_evidence: v.optional(v.array(reference)),
+        assignee: v.optional(reference),
+        assignee_evidence: v.optional(v.array(reference)),
+    }),
+    v.strictObject({
+        ...base,
+        kind: v.literal("fact"),
+        project: v.optional(reference),
+        subject: v.optional(reference),
+        type: v.picklist(FACT_TYPES),
+        statement: text,
+    }),
+    v.strictObject({
+        ...base,
+        kind: v.literal("task_update"),
+        task: reference,
+        change: v.picklist(["close", "due", "detail"]),
+        due_at: v.optional(time),
+        detail: v.optional(text),
+        reason: text,
+    }),
+    v.strictObject({
+        ...base,
+        kind: v.literal("memory"),
+        memory_kind: v.picklist(MEMORY_KINDS),
+        scope: v.picklist(MEMORY_SCOPES),
+        body: text,
+        subject: v.optional(reference),
+        project: v.optional(reference),
+    }),
+    v.strictObject({ ...base, kind: v.literal("link"), from: reference, to: reference, reason: text }),
+    v.strictObject({ ...base, kind: v.literal("new_contact"), address: text, name: text, reason: v.optional(text) }),
+]);
+const outcome = v.strictObject({
+    id,
+    fingerprint: text,
+    status: v.picklist(["accepted", "rejected"]),
+    reference: v.nullable(reference),
+    reused: v.boolean(),
+});
+/** A mail findings batch: what an agent read in one mailbox's new mail, waiting for the owner. */
+export const mailFindings = v.strictObject({
+    id,
+    account: v.strictObject({ provider: text, account: text }),
+    input: v.strictObject({ schema_version: v.literal(1), key: text, extractor: text, findings: v.array(finding) }),
+    fingerprint: text,
+    status: v.picklist(["proposed", "reviewed"]),
+    author,
+    decided_by: v.nullable(v.strictObject({ type: v.picklist(["person", "bot"]), id })),
+    decided_at: v.nullable(time),
+    previous: v.array(outcome),
+    receipt: v.nullable(v.strictObject({ preview_fingerprint: text, accepted: v.array(id), items: v.array(outcome) })),
+});

package/dist/entities/message-context.d.ts

@@ -222,6 +222,9 @@ export declare const messageThread: v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>, undefined>;
@@ -466,6 +469,9 @@ export declare const messageContext: v.UnionSchema<[v.StrictObjectSchema<{
         readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
         readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+        readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>, undefined>;
     readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
 }, undefined>, v.StrictObjectSchema<{
@@ -691,6 +697,9 @@ export declare const messageContext: v.UnionSchema<[v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>, undefined>;

package/dist/entities/message-write.d.ts

@@ -218,6 +218,9 @@ export declare const messageWrite: v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>;
@@ -439,6 +442,9 @@ export declare const messageWrite: v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>, undefined>, undefined>;
@@ -668,6 +674,9 @@ export declare const messageSend: v.UnionSchema<[v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>;
@@ -889,6 +898,9 @@ export declare const messageSend: v.UnionSchema<[v.StrictObjectSchema<{
             readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
             readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
             readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+            readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+            readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+            readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
         }, undefined>, undefined>;
         readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
     }, undefined>, undefined>, undefined>;

package/dist/entities/message.d.ts

@@ -244,6 +244,12 @@ export declare const message: v.StrictObjectSchema<{
         readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
         /** Mail `review`: the mail rule that decided how it is stored, by its id in `rules list`; `null` when none. */
         readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        /** Mail `review`: the evidence fingerprint a finding cites this email by. */
+        readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+        /** Mail `review`: no earlier stored email, in any account, came from this address. */
+        readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        /** Mail `review`: how many identities the sender's person has; 1 is this address alone. */
+        readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>, undefined>;
     readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
 }, undefined>;

package/dist/entities/message.js

@@ -109,6 +109,12 @@ export const message = v.strictObject({
         list_id: v.optional(v.nullable(text)),
         /** Mail `review`: the mail rule that decided how it is stored, by its id in `rules list`; `null` when none. */
         rule_id: v.optional(v.nullable(v.number())),
+        /** Mail `review`: the evidence fingerprint a finding cites this email by. */
+        fingerprint: v.optional(v.pipe(text, v.regex(/^[a-f0-9]{64}$/))),
+        /** Mail `review`: no earlier stored email, in any account, came from this address. */
+        new_sender: v.optional(v.boolean()),
+        /** Mail `review`: how many identities the sender's person has; 1 is this address alone. */
+        sender_identities: v.optional(v.number()),
     })),
     provider_metadata: providerMetadata,
 });

package/dist/entities/store-records.d.ts

@@ -241,6 +241,9 @@ export declare const storeExport: v.UnionSchema<[v.StrictObjectSchema<{
         readonly bulk: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
         readonly list_id: v.OptionalSchema<v.NullableSchema<v.StringSchema<undefined>, undefined>, undefined>;
         readonly rule_id: v.OptionalSchema<v.NullableSchema<v.NumberSchema<undefined>, undefined>, undefined>;
+        readonly fingerprint: v.OptionalSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, undefined>]>, undefined>;
+        readonly new_sender: v.OptionalSchema<v.BooleanSchema<undefined>, undefined>;
+        readonly sender_identities: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
     }, undefined>, undefined>;
     readonly provider_metadata: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.UnknownSchema, undefined>, undefined>;
 }, undefined>, v.StrictObjectSchema<{

package/dist/errors/reasons.js

@@ -44,6 +44,8 @@ const OTHERS = [
     validation("meeting-findings.stale", "meeting findings changed since they were read; stage a new batch"),
     validation("meeting-findings.dedicated-review", "review meeting findings through the dedicated findings command"),
     validation("evidence-findings.stale", "evidence findings changed since they were read; stage a new batch"),
+    validation("mail-findings.stale", "mail findings cite mail that changed since it was read; stage a new batch"),
+    validation("mail-findings.partial", "a cited email is not stored whole yet; cite it once it is"),
     validation("evidence-findings.dedicated-review", "review evidence findings through the dedicated findings command"),
     validation("document.changed", "the document changed while it was read; nothing was saved"),
     ["document.not-imported", "not_found", "the document is not imported in this source account"],

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

@@ -14,6 +14,7 @@ export declare const mailMark: v.StrictObjectSchema<{
         readonly envelope: v.NumberSchema<undefined>;
         readonly partial: v.NumberSchema<undefined>;
         readonly draft: v.NumberSchema<undefined>;
+        readonly suspicious: v.NumberSchema<undefined>;
     }, undefined>;
     readonly updated_at: v.StringSchema<undefined>;
 }, undefined>;

package/dist/mail/cli/marks.js

@@ -3,7 +3,7 @@ import { Command } from "commander";
 import * as v from "valibot";
 import { answerEntity } from "../../cli/answer-entity.js";
 import { outputFor } from "../../cli/context.js";
-import { destroysNothing, LOCAL_WRITE } from "../../cli/effects.js";
+import { LOCAL_WRITE, proposesOnly } from "../../cli/effects.js";
 import { itemOf, renderAnswer } from "../../cli/envelope.js";
 import { acknowledgeMark } from "../marks.js";
 const iso = (ms) => (ms === null ? null : new Date(ms).toISOString());
@@ -14,7 +14,13 @@ export const mailMark = v.strictObject({
     through_received_at: v.nullable(v.string()),
     held: v.number(),
     read: v.number(),
-    skipped: v.strictObject({ bulk: v.number(), envelope: v.number(), partial: v.number(), draft: v.number() }),
+    skipped: v.strictObject({
+        bulk: v.number(),
+        envelope: v.number(),
+        partial: v.number(),
+        draft: v.number(),
+        suspicious: v.number(),
+    }),
     updated_at: v.string(),
 });
 export const markItem = (mark) => ({
@@ -28,12 +34,13 @@ export const markItem = (mark) => ({
 });
 export const markText = (mark) => `${mark.holder}  through ${mark.throughId}${mark.throughAt === null ? "" : ` (${iso(mark.throughAt)})`}  ` +
     `read ${mark.read}  held ${mark.held.length}  skipped bulk ${mark.skipped.bulk}, envelope ${mark.skipped.envelope}, ` +
-    `partial ${mark.skipped.partial}, draft ${mark.skipped.draft}  updated ${iso(mark.updatedAt)}\n`;
+    `partial ${mark.skipped.partial}, draft ${mark.skipped.draft}, suspicious ${mark.skipped.suspicious}  ` +
+    `updated ${iso(mark.updatedAt)}\n`;
 /**
  * `messages acknowledge`: a holder says it is done with what `review --holder` gave it, and its mark moves there. It
  * only moves the holder's own bookkeeping forward, so a read-only scheduled run may do it.
  */
-export const acknowledgeCommand = (mail) => answerEntity(destroysNothing(annotate(new Command("acknowledge"), {
+export const acknowledgeCommand = (mail) => answerEntity(proposesOnly(annotate(new Command("acknowledge"), {
     effects: LOCAL_WRITE,
     examples: [
         `${mail.app.command} personal messages acknowledge --holder mail-triage --cursor 9123.1762090000000`,

package/dist/mail/cli/review.js

@@ -114,6 +114,13 @@ const reviewAnswer = (found, mailbox, fresh) => {
                 bulk: message.marks?.bulk ?? false,
                 list_id: message.marks?.listId ?? null,
                 rule_id: message.marks?.ruleId ?? null,
+                ...(message.marks
+                    ? {
+                        fingerprint: message.marks.fingerprint,
+                        new_sender: message.marks.newSender,
+                        sender_identities: message.marks.senderIdentities,
+                    }
+                    : {}),
             },
         })),
         limit: Math.max(1, read.length),
@@ -202,11 +209,12 @@ 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 and partial mail left out; `messages acknowledge` moves the mark")
+    "bulk, envelopes, drafts, suspicious senders and partial mail left out; `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.
-Every email is shown, mail sent to many too; each item's email says bulk, list_id and rule_id, and its sender_score.
+Every email is shown, mail sent to many too; each item's email says bulk, list_id and rule_id, and its sender_score,
+the fingerprint a finding cites it by, new_sender (no earlier email from the address) and sender_identities.
 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.`)

package/dist/mail/findings.d.ts

@@ -0,0 +1,55 @@
+import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.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. */
+export declare const MAIL_FINDINGS_PER_RUN = 30;
+export declare const MAIL_FINDINGS_PER_SENDER = 5;
+interface Cited {
+    id: string;
+    evidence: FindingEvidence[];
+}
+export type MailTaskFinding = TaskFinding;
+export type MailFactFinding = FactFinding;
+export interface MailTaskUpdateFinding extends Cited {
+    kind: "task_update";
+    task: string;
+    change: "close" | "due" | "detail";
+    dueAt?: string;
+    detail?: string;
+    reason: string;
+}
+export interface MailMemoryFinding extends Cited {
+    kind: "memory";
+    memoryKind: (typeof MEMORY_KINDS)[number];
+    scope: (typeof MEMORY_SCOPES)[number];
+    body: string;
+    subject?: string;
+    project?: string;
+}
+/** Address → person, person → organization, or thread → project. */
+export interface MailLinkFinding extends Cited {
+    kind: "link";
+    from: string;
+    to: string;
+    reason: string;
+}
+export interface MailNewContactFinding extends Cited {
+    kind: "new_contact";
+    address: string;
+    name: string;
+    reason?: string;
+}
+export type MailFinding = MailTaskFinding | MailFactFinding | MailTaskUpdateFinding | MailMemoryFinding | MailLinkFinding | MailNewContactFinding;
+export interface MailFindingsInput {
+    schemaVersion: 1;
+    /** `<holder>:<through_id>`: one batch per run of a holder over the mail it was given. */
+    key: string;
+    extractor: string;
+    findings: MailFinding[];
+}
+/**
+ * The shape of a mail findings batch: 1–30 findings, each citing 1–8 `msg:email/…` references with fingerprints.
+ * What needs the store — the fingerprints, partial mail, the per-sender cap, the targets — the store checks.
+ */
+export declare const validateMailFindings: (input: MailFindingsInput) => MailFindingsInput;
+export declare const mailFindingFingerprint: ({ id: _id, ...finding }: MailFinding) => string;

package/dist/mail/findings.js

@@ -0,0 +1,140 @@
+import { CliError } from "@wirecat/cli-base";
+import { MEMORY_KINDS, MEMORY_SCOPES } from "../domain/knowledge.js";
+import { formatLocator, parseLocator } from "../domain/locator.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";
+/** At most this many findings in one run's batch, and per sender in it. */
+export const MAIL_FINDINGS_PER_RUN = 30;
+export const MAIL_FINDINGS_PER_SENDER = 5;
+const invalid = (message) => {
+    throw new CliError("validation_error", message);
+};
+const emailEvidence = (raw) => {
+    try {
+        const locator = parseLocator(raw);
+        if (locator.provider === "email")
+            return formatLocator(locator);
+    }
+    catch { }
+    return invalid("mail finding evidence is a msg:email/… reference");
+};
+const RULES = {
+    plural: "mail findings",
+    singular: "mail finding",
+    cited: "reference",
+    reference: emailEvidence,
+    anySubject: true,
+    inboxTasks: true,
+};
+const typeOf = (reference) => {
+    try {
+        const parsed = parseReference(reference);
+        return parsed.type === "contact" || parsed.type === "chat" ? `${parsed.type}:${parsed.provider}` : parsed.type;
+    }
+    catch {
+        return undefined;
+    }
+};
+const LINKS = {
+    "contact:email": "person",
+    person: "organization",
+    "chat:email": "project",
+};
+const ADDRESS = /^[^\s@<>]+@[^\s@<>]+$/;
+const one = (raw, ids) => {
+    if (!raw || typeof raw !== "object")
+        return invalid("a finding is an object");
+    if (raw.kind === "task" || raw.kind === "fact")
+        return validateFinding(raw, RULES, ids);
+    const id = findingId(raw.id, ids);
+    const evidence = validEvidence(raw.evidence, RULES);
+    const reference = (value, pattern, what) => {
+        const text = findingText(value, 400);
+        if (!pattern.test(text))
+            return invalid(`${what} is not a reference of the kind it takes: ${text}`);
+        return text;
+    };
+    switch (raw.kind) {
+        case "task_update": {
+            findingFields(raw, ["id", "kind", "task", "change", "dueAt", "detail", "reason", "evidence"], RULES.singular);
+            const task = reference(raw.task, /^task:[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/, "a task update's task");
+            const change = raw.change;
+            if (change !== "close" && change !== "due" && change !== "detail")
+                return invalid("a task update's change is close, due or detail");
+            if ((change === "due") !== (raw.dueAt !== undefined))
+                return invalid("a due change, and only it, gives due_at");
+            if ((change === "detail") !== (raw.detail !== undefined))
+                return invalid("a detail change, and only it, gives detail");
+            return {
+                id,
+                kind: "task_update",
+                task,
+                change,
+                ...(raw.dueAt === undefined
+                    ? {}
+                    : { dueAt: meetingTimestamp(raw.dueAt, "a task update's due date") }),
+                ...(raw.detail === undefined ? {} : { detail: findingText(raw.detail, 2000) }),
+                reason: findingText(raw.reason, 2000),
+                evidence,
+            };
+        }
+        case "memory": {
+            findingFields(raw, ["id", "kind", "memoryKind", "scope", "body", "subject", "project", "evidence"], RULES.singular);
+            if (!MEMORY_KINDS.includes(raw.memoryKind))
+                return invalid(`a memory's memory_kind is ${MEMORY_KINDS.join(", ")}`);
+            if (!MEMORY_SCOPES.includes(raw.scope))
+                return invalid("a memory's scope is personal or work");
+            if (raw.subject === undefined && raw.project === undefined)
+                return invalid("a memory is about a subject or a project");
+            return {
+                id,
+                kind: "memory",
+                memoryKind: raw.memoryKind,
+                scope: raw.scope,
+                body: findingText(raw.body, 20_000),
+                ...(raw.subject === undefined
+                    ? {}
+                    : { subject: reference(raw.subject, /^(person|organization|project):[1-9]\d*$/, "a memory's subject") }),
+                ...(raw.project === undefined ? {} : { project: reference(raw.project, /^project:[1-9]\d*$/, "a project") }),
+                evidence,
+            };
+        }
+        case "link": {
+            findingFields(raw, ["id", "kind", "from", "to", "reason", "evidence"], RULES.singular);
+            const from = findingText(raw.from, 400);
+            const to = findingText(raw.to, 80);
+            const wanted = LINKS[typeOf(from) ?? ""];
+            if (!wanted || typeOf(to) !== wanted || !/:[1-9]\d*$/.test(to))
+                return invalid("a link goes from contact:email/<address> to person:, person: to organization:, or chat:email/… to project:");
+            return { id, kind: "link", from, to, reason: findingText(raw.reason, 2000), evidence };
+        }
+        case "new_contact": {
+            findingFields(raw, ["id", "kind", "address", "name", "reason", "evidence"], RULES.singular);
+            const address = findingText(raw.address, 320).toLowerCase();
+            if (!ADDRESS.test(address))
+                return invalid("a new contact's address is an email address");
+            return {
+                id,
+                kind: "new_contact",
+                address,
+                name: findingText(raw.name, 200),
+                ...(raw.reason === undefined ? {} : { reason: findingText(raw.reason, 2000) }),
+                evidence,
+            };
+        }
+        default:
+            return invalid("a mail finding is a task, task_update, fact, memory, link or new_contact");
+    }
+};
+/**
+ * The shape of a mail findings batch: 1–30 findings, each citing 1–8 `msg:email/…` references with fingerprints.
+ * What needs the store — the fingerprints, partial mail, the per-sender cap, the targets — the store checks.
+ */
+export const validateMailFindings = (input) => {
+    const batch = validateBatch(input, RULES, MAIL_FINDINGS_PER_RUN, one);
+    if (!/^[a-z0-9][a-z0-9-]{0,39}:[1-9]\d*$/.test(batch.key))
+        return invalid("a mail findings key is <holder>:<through_id>, such as mail-triage:9123456");
+    return batch;
+};
+export const mailFindingFingerprint = ({ id: _id, ...finding }) => findingHash(finding);

package/dist/mail/index.d.ts

@@ -1,12 +1,13 @@
 export { mailAccountKey } from "./account-key.js";
 export { BULK, bulkBox } from "./bulk.js";
 export { factsOf } from "./facts.js";
+export { MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, type MailFinding, type MailFindingsInput, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 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, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, type MailMark, type MarkRead, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.js";
+export { acknowledgeMark, cursorOf, HOLD_PARTIAL_MS, HOLDER, holderHasMail, MARK_BATCH, type MailMark, type MarkRead, markOf, marksOf, readPastMark, type SkipReason, } from "./marks.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

@@ -1,12 +1,13 @@
 export { mailAccountKey } from "./account-key.js";
 export { BULK, bulkBox } from "./bulk.js";
 export { factsOf } from "./facts.js";
+export { MAIL_FINDINGS_KIND, MAIL_FINDINGS_PER_RUN, MAIL_FINDINGS_PER_SENDER, mailFindingFingerprint, validateMailFindings, } from "./findings.js";
 export { GMAIL_ALL_MAIL, mailFolders } from "./folders.js";
 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 { acknowledgeMark, cursorOf, HOLD_PARTIAL_MS, HOLDER, MARK_BATCH, markOf, marksOf, readPastMark, } from "./marks.js";
+export { acknowledgeMark, cursorOf, HOLD_PARTIAL_MS, HOLDER, holderHasMail, MARK_BATCH, markOf, marksOf, readPastMark, } from "./marks.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

@@ -5,7 +5,7 @@ export declare const HOLDER: RegExp;
 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";
+export type SkipReason = "bulk" | "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
@@ -28,7 +28,7 @@ export declare const marksOf: (store: MessageStore, mailbox: AccountKey) => Prom
 /** 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;
 export interface MarkRead {
-    /** The emails for the holder, oldest first; bulk, envelopes, drafts and partial mail left out. */
+    /** The emails for the holder, oldest first; bulk, envelopes, drafts, suspicious senders and partial mail left out. */
     emails: StoredHit[];
     /** What `acknowledge --cursor` takes once the holder is done with these. */
     cursor: string;
@@ -44,10 +44,17 @@ export interface MarkRead {
  * only; the mark moves when the holder acknowledges. A holder with no mark starts from now: its first read is
  * empty and gives the cursor of the newest stored email.
  */
-export declare const readPastMark: (store: MessageStore, mailbox: AccountKey, holder: string, { now, limit }?: {
+export declare const readPastMark: (store: MessageStore, mailbox: AccountKey, holder: string, options?: {
     now?: number;
     limit?: number;
 }) => Promise<MarkRead>;
+/**
+ * Whether the holder has mail to read in any stored mailbox — what a schedule asks before it starts the holder's
+ * agent, so a run with nothing new costs no model call. Mail that is only skipped (bulk, envelopes, drafts,
+ * suspicious senders) moves the holder's mark here, as the agent would have acknowledged it, or it would wait
+ * forever behind the mark. A holder with no mark yet has mail to read: its first run sets the mark.
+ */
+export declare const holderHasMail: (store: MessageStore, holder: string, now?: number) => Promise<boolean>;
 /**
  * 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

@@ -8,7 +8,7 @@ export const HOLD_PARTIAL_MS = 7 * 86_400_000;
 /** Held emails kept on one mark at most; past it the oldest are skipped as partial. */
 const MOST_HELD = 500;
 const PREFIX = "consumer:";
-const noneSkipped = () => ({ bulk: 0, envelope: 0, partial: 0, draft: 0 });
+const noneSkipped = () => ({ bulk: 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}"`);
@@ -59,6 +59,8 @@ const verdict = (email, now) => {
         return "envelope";
     if (email.bulk)
         return "bulk";
+    if (email.demoted)
+        return "suspicious";
     if (email.partial)
         return now - email.storedAt < HOLD_PARTIAL_MS ? "held" : "partial";
     return "read";
@@ -76,10 +78,15 @@ const parseCursor = (cursor) => {
  * only; the mark moves when the holder acknowledges. A holder with no mark starts from now: its first read is
  * empty and gives the cursor of the newest stored email.
  */
-export const readPastMark = async (store, mailbox, holder, { now = Date.now(), limit = MARK_BATCH } = {}) => {
+export const readPastMark = async (store, mailbox, holder, options = {}) => {
+    const { wanted, ...read } = await examine(store, mailbox, holder, options);
+    return { emails: await store.mail.emailHits(wanted), ...read };
+};
+/** `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 }) => {
     const mark = await markOf(store, mailbox, holder);
     const account = await accountOf(store, mailbox);
-    const empty = { emails: [], more: false, held: 0, skipped: noneSkipped(), mark };
+    const empty = { wanted: [], more: false, held: 0, skipped: noneSkipped(), mark };
     if (!account)
         return { ...empty, cursor: cursorOf(0, now) };
     if (!mark)
@@ -105,9 +112,8 @@ export const readPastMark = async (store, mailbox, holder, { now = Date.now(), l
         else if (email.id > mark.throughId)
             skipped[said] += 1;
     }
-    const emails = await store.mail.emailHits(wanted.sort((a, b) => a - b));
     return {
-        emails,
+        wanted: wanted.sort((a, b) => a - b),
         cursor: cursorOf(batch.at(-1)?.id ?? mark.throughId, now),
         more: after.length > batch.length,
         held,
@@ -115,6 +121,29 @@ export const readPastMark = async (store, mailbox, holder, { now = Date.now(), l
         mark,
     };
 };
+/**
+ * Whether the holder has mail to read in any stored mailbox — what a schedule asks before it starts the holder's
+ * agent, so a run with nothing new costs no model call. Mail that is only skipped (bulk, envelopes, drafts,
+ * suspicious senders) moves the holder's mark here, as the agent would have acknowledged it, or it would wait
+ * forever behind the mark. A holder with no mark yet has mail to read: its first run sets the mark.
+ */
+export const holderHasMail = async (store, holder, now = Date.now()) => {
+    for (const mailbox of await store.accounts.accounts()) {
+        if (mailbox.provider !== "email")
+            continue;
+        for (;;) {
+            const read = await examine(store, mailbox, holder, { now });
+            if (!read.mark || read.wanted.length > 0)
+                return true;
+            if (read.cursor === cursorOf(read.mark.throughId, now))
+                break;
+            await acknowledgeMark(store, mailbox, holder, read.cursor, now);
+            if (!read.more)
+                break;
+        }
+    }
+    return false;
+};
 /**
  * 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.