@wirecat/cli-core 0.546.0 → 0.548.0

package/dist/mail/sync-types.d.ts

@@ -0,0 +1,112 @@
+import type { BudgetStop, RunBudget } from "../background/budget.js";
+import type { LoadEngine } from "../readers/types.js";
+import type { AccountKey, MessageStore } from "../store/index.js";
+import type { PartialOutcome } from "./partial.js";
+import type { TagOutcome } from "./rule-tags.js";
+import type { MailRule } from "./rules.js";
+import type { DomainAge } from "./score.js";
+export interface MailAccount {
+    /** The mailbox address: the store's account id. */
+    address: string;
+    mode?: "gmail" | "imap" | "mbox";
+    folders?: string[];
+    rules?: MailRule[];
+}
+/** What an index step reports, as memo's embedding does; the sync only passes it on. */
+export interface MailIndexed {
+    chats: number;
+    chunks: number;
+    left: boolean;
+    notEmbedded?: unknown;
+}
+export interface MailSyncResult {
+    account: string;
+    since: string;
+    listed: number;
+    saved: number;
+    alreadyStored: number;
+    /** New emails a skip rule kept out: never read, never stored. */
+    skipped: number;
+    /** New emails an envelope rule recorded: sender, date, size and labels, never their text. */
+    envelopes: number;
+    deleted: number;
+    /** False when `max` stopped the run before every new message was read; the next run continues. */
+    complete: boolean;
+    /** `partial`: a budgeted run stopped before the whole window was read; the next run goes on. */
+    state?: "partial" | "complete";
+    /** Why a budgeted run stopped early: its request budget, its deadline, or a cancel. */
+    stopped?: BudgetStop;
+    /** Messages of the window this run did not get to read: left by a budget, or by `max`. */
+    remaining?: number;
+    /** Requests a budgeted run spent. */
+    requests?: number;
+    /** Emails that could not be read or parsed; they are tried again next run. */
+    unreadable?: {
+        message: string;
+        reason: string;
+    }[];
+    /** Why stored messages missing at the source were left alone, when they were. */
+    deletionsSkipped?: string;
+    /** Folders whose server refused SEARCH: left unread, so the run is partial and proves no deletion. */
+    refusedFolders?: string[];
+    /** "resumed": only mail not done before was listed; "full": every message in the window was. */
+    pass?: "full" | "resumed";
+    indexed?: MailIndexed;
+    coverage?: {
+        folders: string[];
+        since: string;
+        until: string;
+        state: "window" | "partial";
+        identity: string;
+    };
+    attachments?: {
+        message: string;
+        part: number;
+        status: string;
+    }[];
+    /** Rule tags put on mail as an existing label the store pointed to. */
+    tagsReused?: TagOutcome["reused"];
+    /** Rule tags the store refused with nothing to reuse; that mail is stored untagged. */
+    tagsSkipped?: TagOutcome["skipped"];
+    /** Emails a server search stored from their first bytes, read whole this run, and those still partial. */
+    partial?: PartialOutcome;
+    /** `--retry-attachments`: emails read again for attachments a missing reader left unread. */
+    retried?: {
+        emails: number;
+        extracted: number;
+        stillFailed: number;
+        missing: number;
+    };
+}
+export interface MailSyncOptions {
+    account: MailAccount;
+    since: Date;
+    max?: number;
+    maxBodyChars?: number;
+    maxAttachmentChars?: number;
+    now?: () => number;
+    /** Domain registration dates already known, for the sender score a rule asks for. */
+    ages?: ReadonlyMap<string, DomainAge>;
+    loadEngine?: LoadEngine;
+    retryAttachments?: boolean;
+    /** List every message in the window, not only those an earlier run left: proves deletions, refreshes labels. */
+    rescan?: boolean;
+    /** `false` for a spot read, like the copy of a sent message: the run leaves the saved coverage as the last full run set it. */
+    saveCoverage?: boolean;
+    /** A window smaller than this is listed whole every run: it costs seconds and keeps flags and deletions current. */
+    resumeFrom?: number;
+    /** Runs after the mail is saved, so chats and mail still waiting for vectors are indexed; its answer is `indexed`. */
+    index?: (store: MessageStore, key: AccountKey) => Promise<MailIndexed>;
+    /** Stops between batches of emails, after saving the resume point. */
+    signal?: AbortSignal;
+    /**
+     * Makes the run budgeted: it reads the window in rounds, one request of the budget per call to the source, saves
+     * after each, stops when the budget says so and answers `state: "partial"`. A message the source could not give
+     * is tried once more at the end of the run and, if it still fails, left for the next one. `max` defaults to no limit.
+     */
+    budget?: RunBudget;
+    /** Pauses before a round is read again after the store was locked; tests pass one that does not wait. */
+    wait?: (ms: number) => Promise<void>;
+    /** `false` for a spot read: emails a server search stored from their first bytes are not read whole this run. */
+    completePartial?: boolean;
+}

package/dist/mail/sync-types.js

@@ -0,0 +1 @@
+export {};

package/dist/mail/sync.d.ts

@@ -1,109 +1,7 @@
-import type { BudgetStop, RunBudget } from "../background/budget.js";
-import type { LoadEngine } from "../readers/types.js";
-import type { AccountKey, MessageStore } from "../store/index.js";
-import { type TagOutcome } from "./rule-tags.js";
-import { type MailRule } from "./rules.js";
-import type { DomainAge } from "./score.js";
-import type { MailSource } from "./source.js";
-export interface MailAccount {
-    /** The mailbox address: the store's account id. */
-    address: string;
-    mode?: "gmail" | "imap" | "mbox";
-    folders?: string[];
-    rules?: MailRule[];
-}
-/** What an index step reports, as memo's embedding does; the sync only passes it on. */
-export interface MailIndexed {
-    chats: number;
-    chunks: number;
-    left: boolean;
-    notEmbedded?: unknown;
-}
-export interface MailSyncResult {
-    account: string;
-    since: string;
-    listed: number;
-    saved: number;
-    alreadyStored: number;
-    /** New emails a skip rule kept out: never read, never stored. */
-    skipped: number;
-    /** New emails an envelope rule recorded: sender, date, size and labels, never their text. */
-    envelopes: number;
-    deleted: number;
-    /** False when `max` stopped the run before every new message was read; the next run continues. */
-    complete: boolean;
-    /** `partial`: a budgeted run stopped before the whole window was read; the next run goes on. */
-    state?: "partial" | "complete";
-    /** Why a budgeted run stopped early: its request budget, its deadline, or a cancel. */
-    stopped?: BudgetStop;
-    /** Messages of the window this run did not get to read: left by a budget, or by `max`. */
-    remaining?: number;
-    /** Requests a budgeted run spent. */
-    requests?: number;
-    /** Emails that could not be read or parsed; they are tried again next run. */
-    unreadable?: {
-        message: string;
-        reason: string;
-    }[];
-    /** Why stored messages missing at the source were left alone, when they were. */
-    deletionsSkipped?: string;
-    /** "resumed": only mail not done before was listed; "full": every message in the window was. */
-    pass?: "full" | "resumed";
-    indexed?: MailIndexed;
-    coverage?: {
-        folders: string[];
-        since: string;
-        until: string;
-        state: "window" | "partial";
-        identity: string;
-    };
-    attachments?: {
-        message: string;
-        part: number;
-        status: string;
-    }[];
-    /** Rule tags put on mail as an existing label the store pointed to. */
-    tagsReused?: TagOutcome["reused"];
-    /** Rule tags the store refused with nothing to reuse; that mail is stored untagged. */
-    tagsSkipped?: TagOutcome["skipped"];
-    /** `--retry-attachments`: emails read again for attachments a missing reader left unread. */
-    retried?: {
-        emails: number;
-        extracted: number;
-        stillFailed: number;
-        missing: number;
-    };
-}
+import type { MessageStore } from "../store/index.js";
+import { type MailSource } from "./source.js";
+import type { MailSyncOptions, MailSyncResult } from "./sync-types.js";
+export type { MailAccount, MailIndexed, MailSyncOptions, MailSyncResult } from "./sync-types.js";
 export { MAX_ATTACHMENT_CHARS } from "./attachments.js";
 export { RETRYABLE_ATTACHMENTS } from "./retry.js";
-export interface MailSyncOptions {
-    account: MailAccount;
-    since: Date;
-    max?: number;
-    maxBodyChars?: number;
-    maxAttachmentChars?: number;
-    now?: () => number;
-    /** Domain registration dates already known, for the sender score a rule asks for. */
-    ages?: ReadonlyMap<string, DomainAge>;
-    loadEngine?: LoadEngine;
-    retryAttachments?: boolean;
-    /** List every message in the window, not only those an earlier run left: proves deletions, refreshes labels. */
-    rescan?: boolean;
-    /** `false` for a spot read, like the copy of a sent message: the run leaves the saved coverage as the last full run set it. */
-    saveCoverage?: boolean;
-    /** A window smaller than this is listed whole every run: it costs seconds and keeps flags and deletions current. */
-    resumeFrom?: number;
-    /** Runs after the mail is saved, so chats and mail still waiting for vectors are indexed; its answer is `indexed`. */
-    index?: (store: MessageStore, key: AccountKey) => Promise<MailIndexed>;
-    /** Stops between batches of emails, after saving the resume point. */
-    signal?: AbortSignal;
-    /**
-     * Makes the run budgeted: it reads the window in rounds, one request of the budget per call to the source, saves
-     * after each, stops when the budget says so and answers `state: "partial"`. A message the source could not give
-     * is tried once more at the end of the run and, if it still fails, left for the next one. `max` defaults to no limit.
-     */
-    budget?: RunBudget;
-    /** Pauses before a round is read again after the store was locked; tests pass one that does not wait. */
-    wait?: (ms: number) => Promise<void>;
-}
 export declare const syncMail: (source: MailSource, store: MessageStore, options: MailSyncOptions) => Promise<MailSyncResult>;

package/dist/mail/sync.js

@@ -12,11 +12,13 @@ import { dropMissing, tooManyGone } from "./gone.js";
 import { mailHeadersOf } from "./headers.js";
 import { flagsToRefresh, proveByLocation } from "./locations.js";
 import { MAX_BODY_CHARS, parseMail } from "./parse.js";
+import { completePartial } from "./partial.js";
 import { FETCH_SLICE, keyOf, readQuick } from "./quick.js";
 import { FULL_PASS_MS, MBOX_RESUME, mergeRanges, parsePoint, rangesOf, resumeKey, rulesKey, within, } from "./resume.js";
 import { retryUnread } from "./retry.js";
 import { ruleTagger, settleRuleTags } from "./rule-tags.js";
 import { decide, ENVELOPE, envelopeBox, envelopeBoxOf, tagsOf } from "./rules.js";
+import { searchRefused } from "./source.js";
 const DAY = 86_400_000;
 /** IMAP's SINCE counts whole days in the server's zone, so the window's first days are not trusted. */
 const EDGE = 2 * DAY;
@@ -32,6 +34,29 @@ const LIST_SLICE = 200;
 const STORE_BUSY_TRIES = 5;
 const STORE_BUSY_WAIT_MS = 2_000;
 export const syncMail = async (source, store, options) => {
+    const result = await syncRounds(source, store, options);
+    if (options.completePartial === false || options.retryAttachments || options.account.mode === "mbox")
+        return result;
+    if (result.stopped !== undefined || options.signal?.aborted)
+        return result;
+    const partial = await completePartial({
+        store,
+        source,
+        accountId: await store.accounts.saveAccount(mailAccountKey(options.account.address), {
+            name: options.account.address,
+        }),
+        address: options.account.address,
+        folders: () => mailFolders(options.account, source),
+        maxBodyChars: options.maxBodyChars ?? MAX_BODY_CHARS,
+        maxAttachmentChars: options.maxAttachmentChars ?? MAX_ATTACHMENT_CHARS,
+        loadEngine: options.loadEngine ?? importEngine,
+        now: (options.now ?? Date.now)(),
+        ...(options.budget ? { take: () => options.budget?.take() ?? null } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    return partial.completed || partial.left ? { ...result, partial } : result;
+};
+const syncRounds = async (source, store, options) => {
     const { budget, index } = options;
     if (budget === undefined || options.retryAttachments || options.account.mode === "mbox")
         return syncRound(source, store, options);
@@ -45,6 +70,7 @@ export const syncMail = async (source, store, options) => {
         unlisted: new Set(),
         quick: new Map(),
         quickFolders: new Set(),
+        refused: new Set(),
         stopped: null,
         remaining: 0,
         asked: 0,
@@ -195,10 +221,16 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
     /** A quick folder's stored mail as it was before this run changed anything, with the UID of each. */
     const folderMail = new Map();
     const refreshed = new Map();
+    /** Folders whose server refused SEARCH: nothing of them is known, so nothing of them is proved or moved. */
+    const refused = new Set();
     const holdsMail = async (folder) => (await store.mail.emails({ accountId, mailbox: folder, limit: 1 })).length > 0;
     for (const folder of folders) {
         if (mboxPoint !== undefined)
             break;
+        if (plan?.refused.has(folder)) {
+            refused.add(folder);
+            continue;
+        }
         let searched;
         if (source.search !== undefined && !snapshot) {
             searched = plan?.searches.get(folder);
@@ -209,7 +241,16 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                     capped = true;
                     continue;
                 }
-                searched = await source.search(since, folder);
+                try {
+                    searched = await source.search(since, folder);
+                }
+                catch (error) {
+                    if (!searchRefused(error))
+                        throw error;
+                    refused.add(folder);
+                    plan?.refused.add(folder);
+                    continue;
+                }
                 plan?.searches.set(folder, searched);
             }
         }
@@ -380,6 +421,8 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
     let skipped;
     if (snapshot)
         skipped = "an mbox file is a snapshot; mail missing from it is not proven deleted";
+    else if (refused.size > 0)
+        skipped = `the server refused to search ${[...refused].join(", ")}; no deletion is checked until it answers`;
     else if (plan !== undefined && (capped || plan.tried.size > plan.asked || plan.only !== undefined))
         skipped = "this run read the window in parts; a run that lists all of it at once checks deletions";
     else if (quickRan.size > 0) {
@@ -427,7 +470,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         skipped ??= older.skipped;
     }
     if (!snapshot)
-        await store.mail.setMailboxes(accountId, folders.map(mailbox), new Map([...foundFolders].map(([id, found]) => [id, [...found]])), startedAt);
+        await store.mail.setMailboxes(accountId, folders.filter((folder) => !refused.has(folder)).map(mailbox), new Map([...foundFolders].map(([id, found]) => [id, [...found]])), startedAt);
     // A message's label list is whole, so every label the account has is replaced for each message read.
     if (labelsOf.size && !snapshot) {
         const known = (await store.mail.mailboxes(accountId)).filter(({ kind }) => kind === "label");
@@ -766,7 +809,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
                     ],
                 ]),
         ]), startedAt);
-    const incomplete = capped || (plan !== undefined && (plan.stopped !== null || plan.failed.size > 0));
+    const incomplete = capped || refused.size > 0 || (plan !== undefined && (plan.stopped !== null || plan.failed.size > 0));
     const complete = !full && !incomplete && unreadable.length === 0 && (plan?.unreadable.size ?? 0) === 0;
     const bulk = new Map(listed.filter((item) => item.headers?.bulk).map((item) => [item.messageId, [bulkBox.externalId]]));
     if (bulk.size)
@@ -782,7 +825,8 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         state: complete ? "window" : "partial",
         identity: account.mode === "imap" ? "message-id-or-uidvalidity-folder-uid" : "gmail-message-id",
     };
-    if (!snapshot && saveCoverage)
+    // A refused folder says nothing of its mail, so the coverage an earlier run proved stays as it was.
+    if (!snapshot && saveCoverage && refused.size === 0)
         await store.sync.setSyncState(key, "mail_coverage", JSON.stringify(coverage));
     const tagging = tagger.outcome();
     await settleRuleTags(store, accountId, rules, tagging);
@@ -802,6 +846,7 @@ const syncRound = async (source, store, { account, since, max = 200, maxBodyChar
         ...(attachments.length ? { attachments } : {}),
         ...(unreadable.length ? { unreadable } : {}),
         ...(skipped === undefined ? {} : { deletionsSkipped: skipped }),
+        ...(refused.size ? { refusedFolders: [...refused] } : {}),
         ...(searches.size > 0 ? { pass: resumed.size > 0 ? "resumed" : "full" } : {}),
         ...(tagging.reused.length ? { tagsReused: tagging.reused } : {}),
         ...(tagging.skipped.length ? { tagsSkipped: tagging.skipped } : {}),

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

@@ -1,6 +1,6 @@
 import type { FileStamp } from "../resume.js";
 import type { MailCriteria } from "../server-query.js";
-import type { MailSource } from "../source.js";
+import { type MailSource } from "../source.js";
 export type FakePerson = [name: string | null, address: string];
 /** One message of a fake Gmail-like mailbox: its ids, envelope and the parts `rawOf` writes as RFC 5322. */
 export interface FakeMail {
@@ -39,6 +39,8 @@ export interface FakeMailbox {
     validity?: number;
     /** Each answer of `search` and `list` ends in this failure. */
     searchFails?: string;
+    /** Folders whose SEARCH the server refuses: `search` and `query` throw `SEARCH_REFUSED`. */
+    refusesSearch?: string[];
     /** A refused header fetch fails the whole listing. */
     headersFail?: boolean;
     moveFails?: boolean;

package/dist/mail/testing/fake.js

@@ -1,6 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { GMAIL_ALL_MAIL } from "../folders.js";
 import { headersOf } from "../headers.js";
+import { SEARCH_REFUSED } from "../source.js";
 /** As IMAP SEARCH matches: a case-blind substring of the field, every part required. */
 const matches = (m, criteria) => {
     const has = (field, value) => field.toLowerCase().includes(value.toLowerCase());
@@ -73,9 +74,14 @@ export const fakeMailSource = (mailbox) => {
             throw failure(`Gmail has no such mailbox: ${folder}`);
         return mailbox.messages.filter((m) => (folder === trash() ? m.folder === "trash" : m.folder !== "trash") && !m.absentFrom?.includes(folder));
     };
+    const refuse = (folder) => {
+        if (mailbox.refusesSearch?.includes(folder))
+            throw new CliError("provider_error", `the mail server refused to search ${folder}`, { reason: SEARCH_REFUSED });
+    };
     const search = async (since, folder) => {
         if (mailbox.searchFails)
             throw failure(mailbox.searchFails);
+        refuse(folder);
         const from = Date.UTC(since.getUTCFullYear(), since.getUTCMonth(), since.getUTCDate());
         return {
             validity: String(mailbox.validity ?? 12),
@@ -137,6 +143,7 @@ export const fakeMailSource = (mailbox) => {
             count("search");
             if (mailbox.searchFails)
                 throw failure(mailbox.searchFails);
+            refuse(folder);
             mailbox.queried?.push({ criteria, folder });
             return {
                 validity: String(mailbox.validity ?? 12),
@@ -180,14 +187,15 @@ export const fakeMailSource = (mailbox) => {
                 if (messageIds.includes(m.messageId))
                     m.labels = [...new Set([...(m.labels ?? []), ...labels])];
         },
-        fetchRaw: async (items) => {
+        fetchRaw: async (items, options) => {
             count("fetchRaw");
             mailbox.read?.push(...items.map(({ uid }) => uid));
             return items.map((item) => {
                 const m = mailbox.messages.find((each) => each.uid === item.uid);
                 if (m === undefined || mailbox.unreadable?.includes(item.uid) || failsNow(item.uid))
                     return failure(`email ${item.uid} was not read`);
-                return rawOf(m);
+                const raw = rawOf(m);
+                return options?.bytes === undefined ? raw : raw.subarray(0, options.bytes);
             });
         },
     };

package/dist/meetings/event-store.d.ts

@@ -253,6 +253,16 @@ export interface EventStore {
     saveCalendars(accountId: number, calendars: CalendarInput[], now: number): Promise<StoredCalendar[]>;
     calendars(accountId: number): Promise<StoredCalendar[]>;
     setCalendarSynced(calendarId: number, synced: boolean, now: number): Promise<void>;
+    /**
+     * The calendar and everything stored from it go, for a calendar that is not the owner's data (a followed feed): its
+     * entries, the events and series only it held, what was built from them (links, tags, search pieces, people seen
+     * only there) and its cursor. An event another calendar also holds stays, with that copy's fields; a meeting linked
+     * to a gone event stays, unlinked. Notes the owner wrote stay.
+     */
+    forgetCalendar(calendarId: number, now: number): Promise<{
+        entries: number;
+        events: number;
+    }>;
     /** One sync page, matched by rules 1–5, in one transaction. */
     saveEntries(calendarId: number, entries: EntryInput[], now: number): Promise<StoredEntry[]>;
     /**

package/dist/meetings/testing/event-store-contract.js

@@ -192,6 +192,42 @@ export const eventStoreContract = (make) => {
             assert.equal(occurrence?.entries[0]?.deletedAt, null);
             assert.equal(await store.removeEntries(calendar, ["p"], CONTRACT_NOW + 1), 0);
         }),
+        test("a forgotten calendar goes with its entries and the events only it held; a shared event keeps the other copy", async (fixture) => {
+            const { store, calendar, accountId } = fixture;
+            const feed = await second(fixture, "ics:example");
+            await store.saveEntries(calendar, [single("w1", later, { icalUid: "shared@example.com", title: "Mine" })], 2);
+            const series = {
+                ...single("weekly", later, { title: "Weekly" }),
+                kind: "series",
+                recurrence: ["RRULE:FREQ=WEEKLY"],
+            };
+            await store.saveEntries(feed, [
+                single("f1", later, { icalUid: "shared@example.com", title: "Theirs", description: "longer text" }),
+                single("f2", later + HOUR, { title: "Only in the feed", participants: [{ email: "guest@example.com" }] }),
+                series,
+            ], 3);
+            await store.saveSlots(feed, [
+                {
+                    series: "weekly",
+                    slots: [
+                        {
+                            ...single("weekly@1", later + 2 * HOUR),
+                            kind: "occurrence",
+                            seriesExternalId: "weekly",
+                            originalStartsAt: later + 2 * HOUR,
+                        },
+                    ],
+                },
+            ], { from: earlier, to: later + 7 * 24 * HOUR }, "cursor", 3);
+            await store.setCursor(feed, "cursor", 3);
+            const forgotten = await store.forgetCalendar(feed, 4);
+            assert.deepEqual(forgotten, { entries: 4, events: 2 });
+            assert.deepEqual((await store.calendars(accountId)).map(({ externalId }) => externalId), ["primary"]);
+            const left = await store.events({ accountId });
+            assert.deepEqual(left.map(({ title, status }) => [title, status]), [["Mine", "confirmed"]]);
+            assert.equal((await store.event(left[0]?.id))?.entries.length, 1);
+            assert.equal(await store.entry(feed, "weekly"), null);
+        }),
         test("a calendar's cursor is its own, and null forgets it", async (fixture) => {
             const { store, calendar } = fixture;
             const other = await second(fixture);

package/dist/services/deps.d.ts

@@ -70,8 +70,6 @@ export declare const storeIfOpen: (deps: ServiceDeps) => Promise<{
 export declare const fromStore: (deps: Pick<ServiceDeps, "offline" | "reads">) => boolean;
 /** What a store-mode read answers for a chat the store holds nothing of. */
 export declare const nothingStored: (messenger: MessengerTraits) => string;
-/** Where a store-mode messenger's history comes from, for what it cannot do. */
-export declare const PUSHED = "this messenger's history is read from the local store";
 export declare const OFFLINE = "--offline answers only from what is kept locally: `chats list|show`, `messages list|show|context|download`, `contacts list|show` and `review`";
 /** Over a connection that is already open — an MCP session holds one for minutes. */
 export declare const onlineDeps: (messenger: ServiceMessenger, adapter: MessengerAdapter, guard: SendGuard, where?: {

package/dist/services/deps.js

@@ -53,8 +53,6 @@ export const storeIfOpen = async (deps) => {
 export const fromStore = (deps) => deps.offline || deps.reads === "store";
 /** What a store-mode read answers for a chat the store holds nothing of. */
 export const nothingStored = (messenger) => `nothing stored for this chat yet — keep \`${typedCommand(messenger.app.command, "serve")}\` running`;
-/** Where a store-mode messenger's history comes from, for what it cannot do. */
-export const PUSHED = "this messenger's history is read from the local store";
 export const OFFLINE = "--offline answers only from what is kept locally: `chats list|show`, `messages list|show|context|download`, `contacts list|show` and `review`";
 /** Over a connection that is already open — an MCP session holds one for minutes. */
 export const onlineDeps = (messenger, adapter, guard, where = {}) => ({

package/dist/services/documents/ingestion.js

@@ -37,7 +37,7 @@ export const documentIngestion = (store, options) => {
             for (let batch = 0;; batch++) {
                 const memories = await store.memories.list({ subject: ref, status, limit: 500 });
                 for (const memory of memories)
-                    await store.memories.markStale(memory.ref);
+                    await store.memories.markStale(memory.ref, "owner");
                 if (memories.length < 500)
                     break;
                 if (batch >= 20)

package/dist/services/documents/knowledge.d.ts

@@ -1,5 +1,5 @@
 import type { QueryAst } from "@wirecat/cli-base/query";
-import type { Author, Fact, Link, LinkInput, LinkListFilter, Memory, MemoryInput, MessageStore, Note } from "../../store/index.js";
+import type { Author, Decider, Fact, Link, LinkInput, LinkListFilter, Memory, MemoryInput, MessageStore, Note } from "../../store/index.js";
 export interface DocumentKnowledge {
     documents(principal: string, query: QueryAst | undefined, page: {
         limit: number;
@@ -14,7 +14,7 @@ export interface DocumentKnowledge {
     }): Promise<string[]>;
     links(principal: string, ref: string, filter?: Omit<LinkListFilter, "from" | "to">): Promise<Link[]>;
     addLink(principal: string, ref: string, input: Omit<LinkInput, "from" | "origin">): Promise<Link>;
-    removeLink(principal: string, ref: string, id: string): Promise<unknown>;
+    removeLink(principal: string, ref: string, id: string, by: Decider): Promise<unknown>;
     notes(principal: string, ref: string, options?: {
         search?: string;
         limit?: number;
@@ -28,7 +28,7 @@ export interface DocumentKnowledge {
     editNote(principal: string, ref: string, noteRef: string, text: string, revision: number): Promise<Note>;
     removeNote(principal: string, ref: string, noteRef: string): Promise<unknown>;
     addMemory(principal: string, ref: string, input: Pick<MemoryInput, "body" | "kind" | "scope" | "status" | "supersedes"> & {
-        author?: MemoryInput["author"];
+        author: MemoryInput["author"];
     }): Promise<Memory>;
     memories(principal: string, ref: string, options?: {
         scope?: Memory["scope"];
@@ -36,7 +36,9 @@ export interface DocumentKnowledge {
         status?: Memory["status"];
         limit?: number;
     }): Promise<Memory[]>;
-    memory(principal: string, ref: string, memoryRef: string, action?: "show" | "confirm" | "stale"): Promise<Memory>;
+    memory(principal: string, ref: string, memoryRef: string, action?: "show"): Promise<Memory>;
+    /** `by` decides: the owner, or an agent for the owner that did not propose it. */
+    memory(principal: string, ref: string, memoryRef: string, action: "confirm" | "stale", by: Decider): Promise<Memory>;
     searchMemories(principal: string, ref: string, query: string, scope?: Memory["scope"]): Promise<{
         items: Memory[];
         limit_reached: boolean;
@@ -45,7 +47,7 @@ export interface DocumentKnowledge {
         statement: string;
         type: Fact["type"];
         scope?: Memory["scope"];
-        by?: Author;
+        by: Author;
         supersedes?: string;
         occurredAt?: string;
     }): Promise<Fact>;
@@ -54,6 +56,8 @@ export interface DocumentKnowledge {
         status?: Fact["status"];
         limit?: number;
     }): Promise<Fact[]>;
-    fact(principal: string, ref: string, factRef: string, action?: "show" | "confirm" | "reverse"): Promise<Fact>;
+    fact(principal: string, ref: string, factRef: string, action?: "show"): Promise<Fact>;
+    /** `by` decides: the owner, or an agent for the owner that did not propose it; only the owner reverses. */
+    fact(principal: string, ref: string, factRef: string, action: "confirm" | "reverse", by: Decider): Promise<Fact>;
 }
 export declare const documentKnowledge: (store: Pick<MessageStore, "notes" | "facts" | "memories" | "knowledge">, folder: (principal: string) => Promise<string | undefined>) => DocumentKnowledge;

package/dist/services/documents/knowledge.js

@@ -1,4 +1,18 @@
 import { CliError } from "@wirecat/cli-base";
+const writer = (by) => {
+    if (by === undefined)
+        throw new CliError("validation_error", "name who writes it: the owner or an agent; there is no default", {
+            reason: "proposal.decider-required",
+        });
+    return by;
+};
+const decider = (by) => {
+    if (by === undefined)
+        throw new CliError("validation_error", "a confirm names who decides: the owner or an agent with a reason", {
+            reason: "proposal.decider-required",
+        });
+    return by;
+};
 export const documentKnowledge = (store, folder) => {
     const document = async (principal, ref) => {
         const note = await store.notes.resolveNote(ref);
@@ -62,13 +76,13 @@ export const documentKnowledge = (store, folder) => {
         },
         addLink: async (principal, ref, input) => {
             await document(principal, ref);
-            return store.notes.addLink({ ...input, from: ref, origin: "owner" });
+            return store.notes.addLink({ ...input, from: ref, origin: input.by === "owner" ? "owner" : "suggested" });
         },
-        removeLink: async (principal, ref, id) => {
+        removeLink: async (principal, ref, id, by) => {
             const links = await port.links(principal, ref);
             if (!links.some((link) => link.id === id && link.origin === "owner"))
                 throw new CliError("not_found", "owner link is not attached to this document");
-            return store.notes.removeLink(id);
+            return store.notes.removeLink(id, by);
         },
         notes: async (principal, ref, options) => {
             await document(principal, ref);
@@ -91,18 +105,18 @@ export const documentKnowledge = (store, folder) => {
             await document(principal, ref);
             if (input.supersedes)
                 await memoryFor(principal, ref, input.supersedes);
-            return store.memories.add({ ...input, subject: ref, evidence: [ref], author: input.author ?? "owner" });
+            return store.memories.add({ ...input, subject: ref, evidence: [ref], author: writer(input.author) });
         },
         memories: async (principal, ref, options) => {
             await document(principal, ref);
             return store.memories.list({ ...options, subject: ref });
         },
-        memory: async (principal, ref, memoryRef, action = "show") => {
+        memory: async (principal, ref, memoryRef, action = "show", by) => {
             const memory = await memoryFor(principal, ref, memoryRef);
             if (action === "confirm")
-                return store.memories.confirm(memory.ref);
+                return store.memories.confirm(memory.ref, decider(by));
             if (action === "stale")
-                return store.memories.markStale(memory.ref);
+                return store.memories.markStale(memory.ref, decider(by));
             return memory;
         },
         searchMemories: async (principal, ref, query, scope) => {
@@ -117,7 +131,7 @@ export const documentKnowledge = (store, folder) => {
             return store.facts.add({
                 type,
                 statement,
-                by: by ?? "owner",
+                by: writer(by),
                 ...(supersedes === undefined ? {} : { supersedes }),
                 ...(occurredAt === undefined ? {} : { occurredAt }),
                 subject: ref,
@@ -129,12 +143,12 @@ export const documentKnowledge = (store, folder) => {
             await document(principal, ref);
             return store.facts.list({ ...options, subject: ref });
         },
-        fact: async (principal, ref, factRef, action = "show") => {
+        fact: async (principal, ref, factRef, action = "show", by) => {
             const fact = await factFor(principal, ref, factRef);
             if (action === "confirm")
-                return store.facts.accept(fact.ref);
+                return store.facts.accept(fact.ref, decider(by));
             if (action === "reverse")
-                return store.facts.reverse(fact.ref);
+                return store.facts.reverse(fact.ref, decider(by));
             return fact;
         },
     };