@wirecat/cli-core 0.549.0 → 0.551.0

package/dist/mail/partial.js

@@ -6,15 +6,29 @@ import { parseMail } from "./parse.js";
 export const PARTIAL = "partial";
 /** How many partial emails one sync reads whole at most; the rest wait for the next run. */
 export const PARTIAL_PER_RUN = 100;
+/** Failed reads after which a partial email is given up on (`partial.stuck`) and stays as it is. */
+export const PARTIAL_TRIES = 3;
 /**
  * Reads whole the emails a server search stored from their first bytes, so the archive holds their attachments too.
- * Sync never reads stored mail again, so without this step a partial email would stay partial. Gmail's are found by
- * their id; elsewhere at a stored location, trusted only when the bytes read there carry the stored id.
+ * Sync never reads stored mail again, so without this step a partial email would stay partial. A source with `find`
+ * finds them by id; elsewhere they are read at their newest stored location under its UIDVALIDITY, trusted only when
+ * `identify` gives the stored id for the bytes read there. Each failed read is counted, and after `PARTIAL_TRIES`, or
+ * at once when the place holds another message, the email is left partial for good.
  */
 export const completePartial = async ({ store, source, accountId, address, folders, maxBodyChars, maxAttachmentChars, loadEngine, now, take, signal, }) => {
-    const { emails, total } = await store.mail.partialEmails(accountId, PARTIAL_PER_RUN);
+    const { emails, total, stuck } = await store.mail.partialEmails(accountId, PARTIAL_PER_RUN);
     if (emails.length === 0)
-        return { completed: 0, left: 0 };
+        return { completed: 0, left: 0, stuck };
+    let given = 0;
+    // A failed read is counted, so an email the server no longer gives is not read whole on every sync forever.
+    const failed = async (email, forGood = false) => {
+        const mark = (email.metadata?.[PARTIAL] ?? {});
+        const tries = Number(mark.tries ?? 0) + 1;
+        const gaveUp = forGood || tries >= PARTIAL_TRIES;
+        await store.mail.markPartial(accountId, email.externalId, { ...mark, tries, ...(gaveUp ? { stuck: true } : {}) });
+        if (gaveUp)
+            given++;
+    };
     const byId = new Map(emails.map((email) => [email.externalId, email]));
     const items = new Map();
     if (source.find) {
@@ -23,21 +37,27 @@ export const completePartial = async ({ store, source, accountId, address, folde
             if (left.length === 0)
                 break;
             if (take?.())
-                return { completed: 0, left: total };
+                return { completed: 0, left: total, stuck };
             for (const found of await source.find(left, folder)) {
                 const email = byId.get(found.messageId);
                 if (email && !items.has(email))
                     items.set(email, found);
             }
         }
+        for (const email of emails)
+            if (!items.has(email))
+                await failed(email);
     }
     else if (source.identify)
         for (const email of emails) {
             const place = email.locations[0];
-            if (place)
+            if (!place)
+                await failed(email, true);
+            else
                 items.set(email, {
                     uid: String(place.uid),
                     folder: place.folder,
+                    validity: place.uidvalidity,
                     receivedAt: new Date(email.receivedAt ?? 0).toISOString(),
                 });
         }
@@ -58,11 +78,15 @@ export const completePartial = async ({ store, source, accountId, address, folde
         const attachments = [];
         for (const [index, [email, item]] of chunk.entries()) {
             const raw = raws[index];
-            if (!(raw instanceof Uint8Array))
+            if (!(raw instanceof Uint8Array)) {
+                await failed(email);
                 continue;
-            // A UID means another message after a UIDVALIDITY change; only the stored id proves it is this one.
-            if (!source.find && source.identify?.(raw, item).messageId !== email.externalId)
+            }
+            // Only the stored id proves the bytes at a stored UID are this email; another one there will not change back.
+            if (!source.find && source.identify?.(raw, item).messageId !== email.externalId) {
+                await failed(email, true);
                 continue;
+            }
             try {
                 const mail = await parseMail(raw, maxBodyChars);
                 const files = await readAttachments(mail, email.externalId, { loadEngine, maxAttachmentChars, at: now, ...(signal ? { signal } : {}) }, attachments);
@@ -87,8 +111,9 @@ export const completePartial = async ({ store, source, accountId, address, folde
             catch {
                 if (signal?.aborted)
                     break;
+                await failed(email);
             }
         }
     }
-    return { completed, left: total - completed };
+    return { completed, left: total - completed - given, stuck: stuck + given };
 };

package/dist/mail/source.d.ts

@@ -24,7 +24,13 @@ export interface Listed {
     headers?: MailHeaders;
 }
 /** A message as `quick` lists it: everything but the ids, which a source without a cheap one reads from the raw bytes. */
-export type Quick = Omit<Listed, "messageId" | "threadId">;
+export type Quick = Omit<Listed, "messageId" | "threadId"> & {
+    /**
+     * The folder's UIDVALIDITY the UID was stored under. `fetchRaw` reads nothing for it when the folder's differs, and
+     * `identify` works the ids out under it.
+     */
+    validity?: string;
+};
 export interface Searched {
     /** Absent when the server does not say; then no UID is trusted across runs. */
     validity?: string;

package/dist/mail/sync.js

@@ -54,7 +54,7 @@ export const syncMail = async (source, store, options) => {
         ...(options.budget ? { take: () => options.budget?.take() ?? null } : {}),
         ...(options.signal ? { signal: options.signal } : {}),
     });
-    return partial.completed || partial.left ? { ...result, partial } : result;
+    return partial.completed || partial.left || partial.stuck ? { ...result, partial } : result;
 };
 const syncRounds = async (source, store, options) => {
     const { budget, index } = options;

package/dist/mcp/app-server.js

@@ -144,6 +144,7 @@ export const serveAppOverHttp = async (command, context, options, http) => {
     const listening = await serveOverHttp(build, {
         ...http,
         appName: app.command,
+        reaches: `your ${options.name}`,
         onCode: (code, expires) => context.renderer.note(context.env[mcpHttpMarker(app.envPrefix)] === undefined
             ? `login code for a new browser app: ${code} (until ${expires.toTimeString().slice(0, 5)}; a new one after each login)`
             : `a new login code for a browser app: \`${app.command} ${context.settings.profile} mcp server status\``),

package/dist/mcp/http/oauth.d.ts

@@ -14,11 +14,12 @@ export interface OwnerLogin {
  * the browser apps need dynamic registration — but nobody gets a token without the one-time code
  * printed in the owner's terminal. Five wrong codes delay further attempts for thirty seconds.
  */
-export declare const ownerLogin: ({ issuer, resource, file, appName, onCode, now, }: {
+export declare const ownerLogin: ({ issuer, resource, file, appName, reaches, onCode, now, }: {
     issuer: URL;
     resource: URL;
     file: string;
     appName: string;
+    reaches?: string;
     /** The code for the next login, for the owner's eyes only: their terminal, or the server's status file. */
     onCode: (code: string, expires: Date) => void;
     now?: () => number;

package/dist/mcp/http/oauth.js

@@ -51,7 +51,7 @@ const redirectAllowed = (uri) => {
  * the browser apps need dynamic registration — but nobody gets a token without the one-time code
  * printed in the owner's terminal. Five wrong codes delay further attempts for thirty seconds.
  */
-export const ownerLogin = ({ issuer, resource, file, appName, onCode, now = () => Date.now(), }) => {
+export const ownerLogin = ({ issuer, resource, file, appName, reaches = `your ${appName} data`, onCode, now = () => Date.now(), }) => {
     const store = tokenFile(file);
     const codes = new Map();
     let login = { value: "", expires: 0 };
@@ -153,7 +153,7 @@ export const ownerLogin = ({ issuer, resource, file, appName, onCode, now = () =
             .join("");
         const who = escapeHtml(client.name ?? "an application");
         const target = new URL(params.get("redirect_uri") ?? "");
-        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(appName)} login</title><style>body{font:16px system-ui,sans-serif;max-width:28rem;margin:3rem auto;padding:0 1rem;color:#1d2430}input[type=text]{font:20px ui-monospace,monospace;letter-spacing:.1em;width:100%;padding:.5rem;margin:.5rem 0 1rem;box-sizing:border-box}button{font:inherit;padding:.5rem 1rem}.error{color:#b42318}</style></head><body><h1>${escapeHtml(appName)}</h1><p>An app that calls itself <strong>${who}</strong> asks to reach your messages through <code>${escapeHtml(appName)} mcp --http</code>.</p><p>After you allow it, the login goes to <strong>${escapeHtml(target.host)}</strong>. Allow only if that is the app you are connecting, such as chatgpt.com or claude.ai.</p><p>Type the code shown in WireCat Desktop, or in the terminal where the server runs. If you did not start this login, close this page.</p>${message ? `<p class="error">${escapeHtml(message)}</p>` : ""}<form method="post" action="${escapeHtml(`${base}/authorize`)}">${hidden}<label>Login code<input type="text" name="login_code" autocomplete="off" autofocus required></label><button type="submit">Allow</button></form></body></html>`;
+        const html = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(appName)} login</title><style>body{font:16px system-ui,sans-serif;max-width:28rem;margin:3rem auto;padding:0 1rem;color:#1d2430}input[type=text]{font:20px ui-monospace,monospace;letter-spacing:.1em;width:100%;padding:.5rem;margin:.5rem 0 1rem;box-sizing:border-box}button{font:inherit;padding:.5rem 1rem}.error{color:#b42318}</style></head><body><h1>${escapeHtml(appName)}</h1><p>An app that calls itself <strong>${who}</strong> asks to reach ${escapeHtml(reaches)} through <code>${escapeHtml(appName)} mcp serve --http</code>.</p><p>After you allow it, the login goes to <strong>${escapeHtml(target.host)}</strong>. Allow only if that is the app you are connecting, such as chatgpt.com or claude.ai.</p><p>Type the code shown in WireCat Desktop, or in the terminal where the server runs. If you did not start this login, close this page.</p>${message ? `<p class="error">${escapeHtml(message)}</p>` : ""}<form method="post" action="${escapeHtml(`${base}/authorize`)}">${hidden}<label>Login code<input type="text" name="login_code" autocomplete="off" autofocus required></label><button type="submit">Allow</button></form></body></html>`;
         return new Response(html, {
             status: message ? 400 : 200,
             headers: {

package/dist/mcp/http/serve.d.ts

@@ -13,6 +13,8 @@ export interface HttpOptions {
     /** Where the hashes of issued tokens and registered clients are kept. */
     tokenFile: string;
     appName: string;
+    /** What the browser login page says an app asks to reach: `your messages`, `your Google Calendar`. */
+    reaches?: string;
     onCode: (code: string, expires: Date) => void;
     onError?: (error: Error) => void;
     now?: () => number;

package/dist/mcp/http/serve.js

@@ -91,7 +91,7 @@ const toolsIn = async (request) => {
  * the owner's browser cannot reach the port through a rebound DNS name.
  */
 export const serveOverHttp = async (build, options) => {
-    const { publicUrl, port, tokenFile, appName, onCode, onError, now, lockFile, version } = options;
+    const { publicUrl, port, tokenFile, appName, reaches, onCode, onError, now, lockFile, version } = options;
     const lock = lockFile
         ? httpLock(lockFile, {
             pid: process.pid,
@@ -114,6 +114,7 @@ export const serveOverHttp = async (build, options) => {
         resource,
         file: tokenFile,
         appName,
+        ...(reaches ? { reaches } : {}),
         onCode: (code, expires) => {
             lock?.update({ loginCode: code, loginCodeExpiresAt: expires.toISOString() });
             onCode(code, expires);

package/dist/mcp/server.js

@@ -417,6 +417,7 @@ export const serveOverHttpUntilStopped = async (command, context, messenger, opt
     const listening = await serveOverHttp(build, {
         ...http,
         appName,
+        reaches: "your messages",
         // In the background its log is a file; the code goes only to the lock that `mcp server status` reads.
         onCode: (code, expires) => context.renderer.note(context.env[mcpHttpMarker(appEnvPrefix)] === undefined
             ? `login code for a new browser app: ${code} (until ${expires.toTimeString().slice(0, 5)}; a new one after each login)`

package/dist/mcp/surface.js

@@ -46,7 +46,7 @@ const runnableOnly = (result, offered) => {
     const body = result.structuredContent;
     if (result.isError || !Array.isArray(body?.next))
         return result;
-    const next = body.next.filter((step) => offered(step.command));
+    const next = body.next.filter((step) => step.command === undefined || offered(step.command));
     const { next: _, ...rest } = body;
     const kept = next.length > 0 ? { ...rest, next } : rest;
     return {

package/dist/meetings/findings-rules.d.ts

@@ -1,4 +1,4 @@
-import { MEETING_FACT_TYPES as FACT_TYPES } from "./meeting-context.js";
+import { FACT_TYPES, type Payment } from "./payment.js";
 declare const TASK_TYPES: readonly ["bug", "feature", "chore"];
 export interface FindingEvidence {
     reference: string;
@@ -14,9 +14,18 @@ interface FindingBase {
 }
 export interface FactFinding extends FindingBase {
     kind: "fact";
-    type: (typeof FACT_TYPES)[number];
+    type: Exclude<(typeof FACT_TYPES)[number], "payment">;
     statement: string;
 }
+/** A payment an agent read; confirming it records a `payment` fact. A paid one supersedes the expected one. */
+export interface PaymentFinding extends FindingBase {
+    kind: "payment";
+    /** The fact's full sentence; without one, the payment's title. */
+    statement?: string;
+    payment: Payment;
+    /** The `fact:` of the expected payment this one replaces, once it is paid or cancelled. */
+    supersedes?: string;
+}
 export interface TaskFinding extends FindingBase {
     kind: "task";
     type: (typeof TASK_TYPES)[number];
@@ -28,7 +37,7 @@ export interface TaskFinding extends FindingBase {
     assignee?: string;
     assigneeEvidence?: string[];
 }
-export type Finding = FactFinding | TaskFinding;
+export type Finding = FactFinding | TaskFinding | PaymentFinding;
 export interface FindingsInput {
     schemaVersion: 1;
     key: string;
@@ -59,6 +68,8 @@ export interface FindingsRules {
     reference: (raw: string) => string;
     /** A fact finding may name no project, and any finding may name a subject. */
     anySubject?: boolean;
+    /** Payment findings are staged on a project's evidence, not from a meeting. */
+    payments?: boolean;
 }
 export declare const validateFindings: (input: FindingsInput, rules: FindingsRules) => FindingsInput;
 export declare const findingFingerprint: ({ id: _id, ...finding }: Finding) => string;

package/dist/meetings/findings-rules.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { CliError } from "@wirecat/cli-base";
-import { MEETING_FACT_TYPES as FACT_TYPES } from "./meeting-context.js";
+import { FACT_TYPES, validatePayment } from "./payment.js";
 import { meetingTimestamp } from "./timestamp.js";
 const TASK_TYPES = ["bug", "feature", "chore"];
 const invalid = (message) => {
@@ -69,12 +69,26 @@ export const validateFindings = (input, rules) => {
         };
         if (finding.kind === "fact") {
             fields(finding, ["id", "project", "subject", "evidence", "kind", "type", "statement"], rules.singular);
+            if (finding.type === "payment")
+                return invalid("a payment is a finding of kind payment");
             if (!FACT_TYPES.includes(finding.type))
                 return invalid("unknown fact finding type");
             return { ...base, kind: "fact", type: finding.type, statement: text(finding.statement, 2000) };
         }
+        if (finding.kind === "payment" && rules.payments) {
+            fields(finding, ["id", "project", "subject", "evidence", "kind", "statement", "payment", "supersedes"], rules.singular);
+            if (finding.supersedes !== undefined && !/^fact:[1-9]\d*$/.test(String(finding.supersedes)))
+                return invalid("a payment finding supersedes a fact: reference");
+            return {
+                ...base,
+                kind: "payment",
+                ...(finding.statement === undefined ? {} : { statement: text(finding.statement, 2000) }),
+                payment: validatePayment(finding.payment),
+                ...(finding.supersedes === undefined ? {} : { supersedes: finding.supersedes }),
+            };
+        }
         if (finding.kind !== "task")
-            return invalid("a finding is a fact or task");
+            return invalid(`a finding is a fact${rules.payments ? ", payment" : ""} or task`);
         fields(finding, [
             "id",
             "project",

package/dist/meetings/index.d.ts

@@ -9,17 +9,18 @@ export { entryInWindow, eventChange } from "./event-store.js";
 export { linkEvent } from "./events.js";
 export { exportMeeting, type MeetingExport, type MeetingExportFormat, type MeetingExportOptions, serializeVtt, } from "./export.js";
 export { type FindingEvidence, type FindingOutcome, findingHash, MEETING_FINDINGS_KIND, type MeetingFactFinding, type MeetingFinding, type MeetingFindingsInput, type MeetingFindingsReceipt, type MeetingTaskFinding, meetingFindingFingerprint, validateMeetingFindings, } from "./findings.js";
-export { type Finding, type FindingsInput, type FindingsReceipt, type FindingsRules, findingFingerprint, validateFindings, } from "./findings-rules.js";
+export { type Finding, type FindingsInput, type FindingsReceipt, type FindingsRules, findingFingerprint, type PaymentFinding, validateFindings, } from "./findings-rules.js";
 export { liftMeetingFields, MEETING_HIT_QUERY, meetingWordsQuery, parseMeetingQuery } from "./hit-query.js";
 export { type ImportFile, importFiles } from "./import.js";
 export { MEETING_ISSUES, MEETING_QUERY, type MeetingIssue, type MeetingItem, type MeetingOwner, meeting, meetingIssuesOf, meetingItem, } from "./item.js";
 export { joinKeyOf, joinUrlWithoutQuery } from "./join-key.js";
 export { CHAT_MESSAGES_READ, type MeetingChatLine, type MeetingChatLinesInput, type MeetingChatLinesStore, type MeetingLink, } from "./links.js";
-export { createMeetingContext, MEETING_FACT_TYPES, type MeetingContextAction, type MeetingContextChange, type MeetingContextOperation, type MeetingContextPorts, type MeetingContextReceipt, validateMeetingContextChange, } from "./meeting-context.js";
+export { createMeetingContext, type MeetingContextAction, type MeetingContextChange, type MeetingContextOperation, type MeetingContextPorts, type MeetingContextReceipt, validateMeetingContextChange, } from "./meeting-context.js";
 export { createMeetingManagement, dispatchMeetingMutation, type ManagedMeeting, type ManagedMeetingChange, type MeetingManagement, type MeetingManagementPorts, type MeetingMutationOptions, type MeetingMutationProposal, type MeetingMutationReceipt, type MeetingOperationOptions, type MeetingProviderContext, validateMeetingChange, } from "./meeting-management.js";
 export type { Attachment, ChatLine, Event, EventSeries, JsonValue, Meeting, MeetingSeries, Metadata, Occurrence, Participant, RecordTimes, SourceChatLine, SourceMeeting, Summary, SummaryContent, Transcript, TranscriptLine, TranscriptRow, } from "./model.js";
 export { type MeetingParticipantCandidate, type MeetingParticipantPage, type MeetingParticipantReader, type MeetingParticipantSearchOptions, type MeetingParticipantSearchStore, normalizeMeetingParticipantQuery, validateMeetingParticipantSearch, } from "./participant-search.js";
 export { type MeetingContextCue, type MeetingHitContextOptions, type MeetingHitContextPacket, type MeetingPassageOutputFormat, type MeetingPassageReader, type MeetingPassageRequest, type MeetingPassageResult, meetingHitContextLimits, validateMeetingPassage, } from "./passage.js";
+export { FACT_TYPES, PAYMENT_DIRECTIONS, PAYMENT_STATES, type Payment, paymentTitle, validatePayment, } from "./payment.js";
 export { type MeetingPreparationContext, type MeetingPreparationContextRequest, type MeetingPreparationContextStore, type PreparationPage, validateMeetingPreparationContext, } from "./preparation-context.js";
 export type { MeetingPreparationFact, MeetingPreparationKnowledgeRequest, MeetingPreparationKnowledgeStore, } from "./preparation-knowledge.js";
 export type { MeetingPreparationNote, MeetingPreparationNotesSelection, MeetingPreparationNotesStore, } from "./preparation-notes.js";

package/dist/meetings/index.js

@@ -12,10 +12,11 @@ export { importFiles } from "./import.js";
 export { MEETING_ISSUES, MEETING_QUERY, meeting, meetingIssuesOf, meetingItem, } from "./item.js";
 export { joinKeyOf, joinUrlWithoutQuery } from "./join-key.js";
 export { CHAT_MESSAGES_READ, } from "./links.js";
-export { createMeetingContext, MEETING_FACT_TYPES, validateMeetingContextChange, } from "./meeting-context.js";
+export { createMeetingContext, validateMeetingContextChange, } from "./meeting-context.js";
 export { createMeetingManagement, dispatchMeetingMutation, validateMeetingChange, } from "./meeting-management.js";
 export { normalizeMeetingParticipantQuery, validateMeetingParticipantSearch, } from "./participant-search.js";
 export { meetingHitContextLimits, validateMeetingPassage, } from "./passage.js";
+export { FACT_TYPES, PAYMENT_DIRECTIONS, PAYMENT_STATES, paymentTitle, validatePayment, } from "./payment.js";
 export { validateMeetingPreparationContext, } from "./preparation-context.js";
 export { readMeetingProjectEvidence } from "./project-evidence.js";
 export { meetingProjectEvidence, meetingProjectEvidenceAnswer, } from "./project-evidence-answer.js";

package/dist/meetings/meeting-context.d.ts

@@ -1,7 +1,6 @@
 import { type MeetingMutationOptions } from "./meeting-management.js";
+import { FACT_TYPES } from "./payment.js";
 import { type MeetingProviderScope } from "./provider.js";
-/** Mirrors the store's fact types; the store checks the type again when it writes. */
-export declare const MEETING_FACT_TYPES: readonly ["fact", "statement", "question", "decision", "promise"];
 export type MeetingContextChange = {
     action: "note.add";
     text: string;
@@ -19,7 +18,7 @@ export type MeetingContextChange = {
 } | {
     action: "fact.add";
     statement: string;
-    type: (typeof MEETING_FACT_TYPES)[number];
+    type: (typeof FACT_TYPES)[number];
     scope: "personal" | "work";
     evidence: readonly string[];
     subject?: string;

package/dist/meetings/meeting-context.js

@@ -1,8 +1,7 @@
 import { CliError } from "@wirecat/cli-base";
 import { dispatchMeetingMutation } from "./meeting-management.js";
+import { FACT_TYPES } from "./payment.js";
 import { snapshotMeetingScope } from "./provider.js";
-/** Mirrors the store's fact types; the store checks the type again when it writes. */
-export const MEETING_FACT_TYPES = ["fact", "statement", "question", "decision", "promise"];
 const id = (value) => {
     if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 1)
         throw new CliError("validation_error", "meeting context identifiers must be positive integers");
@@ -63,8 +62,8 @@ export const validateMeetingContextChange = (change) => {
             });
         }
         case "fact.add": {
-            if (!MEETING_FACT_TYPES.includes(change.type) || !["personal", "work"].includes(change.scope))
-                throw new CliError("validation_error", `fact type (${MEETING_FACT_TYPES.join(", ")}) and explicit personal/work scope are required`);
+            if (!FACT_TYPES.includes(change.type) || !["personal", "work"].includes(change.scope))
+                throw new CliError("validation_error", `fact type (${FACT_TYPES.join(", ")}) and explicit personal/work scope are required`);
             return Object.freeze({
                 action: change.action,
                 statement: text(change.statement, 20_000),

package/dist/meetings/payment.d.ts

@@ -0,0 +1,27 @@
+/** Every fact type the store takes; findings and meeting changes check against the same list. */
+export declare const FACT_TYPES: readonly ["fact", "statement", "question", "decision", "promise", "payment"];
+export declare const PAYMENT_DIRECTIONS: readonly ["to_us", "from_us"];
+export declare const PAYMENT_STATES: readonly ["expected", "paid", "cancelled"];
+/** A payment fact's fields, kept in `facts.metadata.payment`. */
+export interface Payment {
+    /** A decimal as text with two places, "50000.00": money is never a float. */
+    amount: string;
+    /** ISO 4217, "RUB". */
+    currency: string;
+    direction: (typeof PAYMENT_DIRECTIONS)[number];
+    /** `person:`, `organization:` or `project:`; `null` when only a name is known. */
+    counterparty: string | null;
+    counterparty_name: string | null;
+    /** An ISO date. */
+    due_at: string | null;
+    /** A change of state is a new fact that supersedes this one, so the history and its evidence stay. */
+    state: (typeof PAYMENT_STATES)[number];
+    /** What it is for, short: "support, September". The fact's statement is the full sentence. */
+    item: string | null;
+}
+/** A payment as stored: the amount with two decimals, the currency upper case; refuses what is not one. */
+export declare const validatePayment: (input: unknown) => Payment;
+/** One line for a payment, as a list or an inbox shows it: "1 200 EUR to us from Ana, due 31.10 (expected)". */
+export declare const paymentTitle: (fact: {
+    payment: Payment | null;
+}) => string;

package/dist/meetings/payment.js

@@ -0,0 +1,81 @@
+import { CliError } from "@wirecat/cli-base";
+/** Every fact type the store takes; findings and meeting changes check against the same list. */
+export const FACT_TYPES = ["fact", "statement", "question", "decision", "promise", "payment"];
+export const PAYMENT_DIRECTIONS = ["to_us", "from_us"];
+export const PAYMENT_STATES = ["expected", "paid", "cancelled"];
+const invalid = (message) => {
+    throw new CliError("validation_error", message);
+};
+const CURRENCIES = new Set(Intl.supportedValuesOf("currency"));
+const AMOUNT = /^(\d{1,15})(?:\.(\d{1,2}))?$/;
+const COUNTERPARTY = /^(person|organization|project):[1-9]\d*$/;
+const amountOf = (value) => {
+    const match = AMOUNT.exec(typeof value === "number" ? String(value) : typeof value === "string" ? value.trim() : "");
+    if (!match)
+        return invalid("a payment's amount is a positive number with at most 2 decimals, such as 1200.50");
+    const amount = `${BigInt(match[1] ?? "0")}.${(match[2] ?? "").padEnd(2, "0")}`;
+    if (amount === "0.00")
+        return invalid("a payment's amount is more than 0");
+    return amount;
+};
+const dateOf = (value) => {
+    const date = typeof value === "string" ? value.trim() : "";
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(date) || new Date(`${date}T00:00:00Z`).toISOString().slice(0, 10) !== date)
+        return invalid("a payment's due date is an ISO date, such as 2026-10-31");
+    return date;
+};
+const optionalText = (value, what, limit) => {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value !== "string" || !value.trim() || value.length > limit || value.includes("\0"))
+        return invalid(`a payment's ${what} takes 1–${limit} characters`);
+    return value.trim();
+};
+const oneOf = (value, allowed, what) => {
+    if (typeof value !== "string" || !allowed.includes(value))
+        return invalid(`a payment's ${what} is one of ${allowed.join(", ")}`);
+    return value;
+};
+const FIELDS = ["amount", "currency", "direction", "counterparty", "counterparty_name", "due_at", "state", "item"];
+/** A payment as stored: the amount with two decimals, the currency upper case; refuses what is not one. */
+export const validatePayment = (input) => {
+    if (!input || typeof input !== "object" || Array.isArray(input))
+        return invalid("a payment is an object");
+    const raw = input;
+    const unknown = Object.keys(raw).filter((key) => !FIELDS.includes(key));
+    if (unknown.length)
+        return invalid(`a payment has no field ${unknown.join(", ")}; its fields are ${FIELDS.join(", ")}`);
+    const currency = typeof raw.currency === "string" ? raw.currency.trim().toUpperCase() : "";
+    if (!/^[A-Z]{3}$/.test(currency) || !CURRENCIES.has(currency))
+        return invalid("a payment's currency is an ISO 4217 code, such as EUR or RUB");
+    const counterparty = optionalText(raw.counterparty, "counterparty", 80);
+    if (counterparty !== null && !COUNTERPARTY.test(counterparty))
+        return invalid("a payment's counterparty is a person:, organization: or project: reference");
+    return {
+        amount: amountOf(raw.amount),
+        currency,
+        direction: oneOf(raw.direction, PAYMENT_DIRECTIONS, "direction"),
+        counterparty,
+        counterparty_name: optionalText(raw.counterparty_name, "counterparty name", 200),
+        due_at: raw.due_at === undefined || raw.due_at === null ? null : dateOf(raw.due_at),
+        state: oneOf(raw.state, PAYMENT_STATES, "state"),
+        item: optionalText(raw.item, "item", 200),
+    };
+};
+const grouped = (amount) => {
+    const [whole = "0", cents = "00"] = amount.split(".");
+    const digits = whole.replace(/\B(?=(\d{3})+(?!\d))/g, " ");
+    return cents === "00" ? digits : `${digits}.${cents}`;
+};
+/** One line for a payment, as a list or an inbox shows it: "1 200 EUR to us from Ana, due 31.10 (expected)". */
+export const paymentTitle = (fact) => {
+    const payment = fact.payment;
+    if (!payment)
+        return "";
+    const who = payment.counterparty_name ?? payment.counterparty;
+    const way = payment.direction === "to_us" ? "to us" : "from us";
+    const party = who === null ? "" : payment.direction === "to_us" ? ` from ${who}` : ` to ${who}`;
+    const due = payment.due_at === null ? "" : `, due ${payment.due_at.slice(8, 10)}.${payment.due_at.slice(5, 7)}`;
+    const item = payment.item === null ? "" : ` for ${payment.item}`;
+    return `${grouped(payment.amount)} ${payment.currency} ${way}${party}${item}${due} (${payment.state})`;
+};

package/dist/services/archive.d.ts

@@ -6,6 +6,7 @@ import { type AccountKey, type ChatStats, type MessageStore, type Range } from "
 import { type Estimate } from "./backfill-estimate.js";
 import { batchProgress } from "./batch.js";
 import type { ServiceDeps } from "./deps.js";
+import { type ChatShape } from "./history-limits.js";
 import { type CatchUpOptions, type CatchUpResult } from "./search-catchup.js";
 /** The most messages a provider hands out per history request — Telegram's cap. */
 export declare const PAGE = 100;
@@ -45,6 +46,10 @@ export interface FetchOptions {
         done: number;
         fetched: number;
     }) => void;
+    /** Past the history limits for this chat (`--full-history`). */
+    fullHistory?: boolean;
+    /** The chat's kind and size as the messenger lists it, for a chat the store does not hold yet. */
+    shape?: ChatShape;
 }
 /** A type, not an interface: a job keeps it as a plain record. */
 export type Fetched = {
@@ -62,6 +67,8 @@ export type Fetched = {
     reachedSince?: true;
     reachedLast?: true;
     stopped?: true;
+    /** The history limits stopped this read: a group too large to read, or the window's start reached. */
+    limited?: "group_too_large" | "older_than_window";
 };
 export type FetchedAll = {
     batch?: ReturnType<ReturnType<typeof batchProgress>["result"]>;
@@ -80,7 +87,13 @@ export type FetchedAll = {
         stopped?: true;
         error?: string;
         issue?: ActionableError;
+        limited?: "group_too_large" | "older_than_window";
     }[];
+    /** How many chats the history limits left unread (big groups) or read only to the window's start. */
+    limited?: {
+        groupTooLarge: number;
+        olderThanWindow: number;
+    };
 };
 /** The local store of messages: what it holds, filling it from the messenger, and reading it out. */
 export interface ArchiveService {

package/dist/services/archive.js

@@ -5,6 +5,7 @@ import { typedCommand } from "../runs/scope.js";
 import { fetchedKey, historyStartKey, } from "../store/store.js";
 import { estimateBackfill } from "./backfill-estimate.js";
 import { actionable, batchProgress } from "./batch.js";
+import { historyWindow } from "./history-limits.js";
 import { storedChatId } from "./message-resolution.js";
 import { patiently } from "./patience.js";
 import { catchUpSearch, validateCatchUp } from "./search-catchup.js";
@@ -114,13 +115,28 @@ export const archiveService = (deps) => {
                 throw new CliError("authentication_error", "the connection belongs to another account");
             if (options.stop.aborted)
                 return { chat: null, fetched: 0, complete: false, ranges: [], stopped: true };
-            const result = await fetchInto({
+            const store = await deps.store();
+            const account = { provider: deps.messenger.provider, account: self };
+            const limit = await limitOf(deps, store, account, chat, options);
+            if (limit?.skip) {
+                await recordSkip(store, account, limit.chatId, { reason: "group_too_large", members: limit.skip.members });
+                return { chat: limit.chatId ?? null, fetched: 0, complete: false, ranges: [], limited: "group_too_large" };
+            }
+            const windowed = limit?.keepFrom !== undefined && !(limit.keepFrom <= (options.sinceMs ?? Number.NEGATIVE_INFINITY));
+            const fetched = await fetchInto({
                 history: (window) => history(chat, { ...window, reactions: false }),
-                store: await deps.store(),
-                account: { provider: deps.messenger.provider, account: self },
+                store,
+                account,
                 fetching: deps.messenger.fetching ?? FETCHING,
                 ...options,
+                ...(windowed ? { sinceMs: limit.keepFrom } : {}),
             });
+            const result = windowed && fetched.reachedSince ? { ...fetched, limited: "older_than_window" } : fetched;
+            if (result.limited && limit?.keepFrom !== undefined)
+                await recordSkip(store, account, result.chat ?? limit.chatId, {
+                    reason: "older_than_window",
+                    keptFrom: new Date(limit.keepFrom).toISOString(),
+                });
             return requested && result.chat
                 ? { ...result, prepared: await catchUpSearch(deps, result.chat, requested, options.stop) }
                 : result;
@@ -161,7 +177,17 @@ export const archiveService = (deps) => {
                     continue;
                 }
                 try {
-                    const one = await own.fetch(chat.id, options);
+                    const one = await own.fetch(chat.id, {
+                        ...options,
+                        shape: { kind: chat.kind, participantsCount: chat.participantsCount ?? null },
+                    });
+                    if (one.limited) {
+                        answer.limited ??= { groupTooLarge: 0, olderThanWindow: 0 };
+                        if (one.limited === "group_too_large")
+                            answer.limited.groupTooLarge += 1;
+                        else
+                            answer.limited.olderThanWindow += 1;
+                    }
                     if (one.issue)
                         batch.fail(chat.id, "history", one.issue);
                     else
@@ -172,7 +198,8 @@ export const archiveService = (deps) => {
                         title: chat.title,
                         fetched: one.fetched,
                         // Reaching the window is what --all asked for; older history was not.
-                        complete: one.complete || one.reachedSince === true || one.reachedLast === true,
+                        complete: one.complete || one.reachedSince === true || one.reachedLast === true || one.limited !== undefined,
+                        ...(one.limited ? { limited: one.limited } : {}),
                         ...(one.issue ? { error: one.issue.code, issue: one.issue } : {}),
                         ...(one.stopped ? { stopped: true } : {}),
                     });
@@ -195,6 +222,30 @@ export const archiveService = (deps) => {
         },
     };
 };
+/**
+ * Where the history limits stop this chat's read: not at all for a group above the cap, else at the window's start.
+ * None for a lifted chat or without limits. A chat the store does not hold yet is judged by the shape the list gave.
+ */
+const limitOf = async (deps, store, account, chat, options) => {
+    if (!deps.historyLimits || options.fullHistory)
+        return undefined;
+    const chatId = await storedChatId(deps.messenger, chat, store, account, { includeLeft: true }).catch(() => undefined);
+    const stored = chatId === undefined ? undefined : (await store.chats.historyShapes(account, [chatId])).get(chatId);
+    if (stored?.included)
+        return undefined;
+    const window = historyWindow(stored ?? options.shape, deps.historyLimits, Date.now());
+    return {
+        ...(chatId === undefined ? {} : { chatId }),
+        ...("skip" in window ? { skip: { members: window.members } } : { keepFrom: window.keepFrom }),
+    };
+};
+/** A read the limits stopped, for `store status` and the answers that say not all is there; the count is unknown. */
+const recordSkip = async (store, account, chatId, skip) => {
+    if (!chatId)
+        return;
+    const at = new Date().toISOString();
+    await store.chats.recordHistorySkips(account, new Map([[chatId, { ...skip, messages: 0, oldestAt: at, newestAt: at, unread: true }]]));
+};
 /** The fetch loop, over any history and store: the personal account's service and a bot's command share it. */
 export const abortable = async (read, signal) => {
     signal.throwIfAborted();