@wirecat/cli-core 0.548.0 → 0.550.0

package/dist/cli/program.js

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { CliError, errorObjectOf, errorRecordOf, exitCodeFor, exitCodeOfError, processStreams, renderError, resolvePaths, } from "@wirecat/cli-base";
 import { metaOf, refuseJoinedPath } from "@wirecat/cli-base/commands";
 import { skillHint } from "@wirecat/cli-base/skill";
+import { COMPACT_FLAG } from "@wirecat/cli-base/standards";
 import { Command, Help } from "commander";
 import { relayCommand } from "../background/relay.js";
 import { failingNotice, scheduledRuns } from "../background/schedules.js";
@@ -17,6 +18,7 @@ import { liftOptionsAfterDashes } from "./after-dashes.js";
 import { logParsedArgv, logVersion } from "./argv-log.js";
 import { commandAvailability } from "./command-availability.js";
 import { commandPathOf } from "./command-contract.js";
+import { entityRows } from "./compact.js";
 import { outputFor, provide } from "./context.js";
 import { refuseByCommandPermissions, refuseWriteBeforeConnecting } from "./early-refusal.js";
 import { changesAuthorityAt, changesAuthorityNow, isLogin, isStoreChange, judgedEffects, judgedTargets, storeChangeRefusal, } from "./effects.js";
@@ -73,6 +75,7 @@ export const createProgram = (definition, { out, err } = {}) => {
         .option("--max-output-bytes <bytes>", "maximum machine output bytes (default: 4194304; 0 disables)")
         .option("--brief", `${found} as reference, title, time, ${messenger ? "sender" : "author"} and excerpt only`)
         .option("--full", `${found} with their whole text and every provider field`)
+        .option(COMPACT_FLAG, "one line per item for an agent: reference first, text last, paging and next steps as # lines")
         .option("--dry-run", "preview parsed arguments and permissions before running the action")
         .option("--yes", "go ahead without the question an ask level puts before a write")
         .option("--record", "keep this run even where the config says record false; record_input false leaves the typed words out")
@@ -82,6 +85,8 @@ export const createProgram = (definition, { out, err } = {}) => {
         program.addCommand(command);
     configure?.(program);
     if (!contractsChecked.has(definition)) {
+        if (definition.rows)
+            entityRows(definition.rows);
         assertSharedContracts(program);
         contractsChecked.add(definition);
     }
@@ -136,7 +141,7 @@ export const run = async (argv, definition, options = {}) => {
         useAsProcessRun(outer);
     }
 };
-const isMachine = (words) => words.some((word) => word === "--json" || word.startsWith("--json=") || word === "--jsonl");
+const isMachine = (words) => words.some((word) => word === "--json" || word.startsWith("--json=") || word === "--jsonl" || word === COMPACT_FLAG);
 const runOnce = async (argv, definition, options) => {
     const streams = options.streams ?? processStreams;
     if (!options.streams)
@@ -218,6 +223,7 @@ const runOnce = async (argv, definition, options) => {
         commandSignal: control.signal,
         trackCloseable: control.trackCloseable,
         app: definition.app,
+        ...(definition.rows ? { rows: definition.rows } : {}),
         platform: options.platform ?? process.platform,
         exit,
         runCommand: (words, given) => run(words, definition, given),

package/dist/domain/providers.d.ts

@@ -1,4 +1,5 @@
 import type { Provider } from "./models.js";
+import { type RefKindName } from "./references.js";
 /** What a search reads; the same names `--only`, `searched` and `skipped` use. */
 export declare const KINDS: readonly ["messages", "mail", "notes", "documents", "meetings", "events"];
 export type Kind = (typeof KINDS)[number];
@@ -8,6 +9,8 @@ export interface ProviderEntry {
     aliases: readonly string[];
     /** The CLI that wrote the entry (`zm`, `drive`). One CLI may write several providers, so it is not an alias. */
     command?: string;
+    /** The read command, after `<command> <profile>`, that opens a ref of each kind: `{ chat: "messages list" }`. */
+    opens?: Partial<Record<RefKindName, string>>;
 }
 /** The seed: what cli-core knows before any CLI has written its entry into the store. */
 export declare const PROVIDERS: readonly ProviderEntry[];

package/dist/domain/providers.js

@@ -1,13 +1,15 @@
 import { CliError } from "@wirecat/cli-base";
+import { REF_KINDS } from "./references.js";
 /** What a search reads; the same names `--only`, `searched` and `skipped` use. */
 export const KINDS = ["messages", "mail", "notes", "documents", "meetings", "events"];
+const MESSENGER_OPENS = { chat: "messages list", message: "messages show", contact: "contacts show" };
 /** The seed: what cli-core knows before any CLI has written its entry into the store. */
 export const PROVIDERS = [
-    { name: "telegram", kind: "messages", aliases: ["tg"], command: "tg" },
+    { name: "telegram", kind: "messages", aliases: ["tg"], command: "tg", opens: MESSENGER_OPENS },
     { name: "telegram-bot", kind: "messages", aliases: ["tg-bot"] },
-    { name: "max", kind: "messages", aliases: [], command: "max" },
+    { name: "max", kind: "messages", aliases: [], command: "max", opens: MESSENGER_OPENS },
     { name: "max-bot", kind: "messages", aliases: [] },
-    { name: "whatsapp", kind: "messages", aliases: ["wa"], command: "wa" },
+    { name: "whatsapp", kind: "messages", aliases: ["wa"], command: "wa", opens: MESSENGER_OPENS },
     { name: "whatsapp-bot", kind: "messages", aliases: ["wa-bot"] },
     { name: "email", kind: "mail", aliases: [] },
     { name: "notes", kind: "notes", aliases: [] },
@@ -58,11 +60,23 @@ const invalid = (message) => {
 const wordOf = (value, what) => typeof value === "string" && WORD.test(value)
     ? value
     : invalid(`${what} is lowercase letters, digits, - and _ — not ${JSON.stringify(value)}`);
+const OPEN_KINDS = new Set(REF_KINDS.map(({ type }) => type).filter((type) => type !== "entity"));
+const COMMAND_WORDS = /^[a-z0-9][a-z0-9_-]*( [a-z0-9][a-z0-9_-]*)*$/;
+/** A kind this build does not know is dropped, not refused: a newer CLI may open kinds added after this release. */
+const opensOf = (value, named) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return invalid(`provider ${named}'s opens maps a kind of reference to a command`);
+    const known = Object.entries(value).filter(([kind]) => OPEN_KINDS.has(kind));
+    for (const [kind, command] of known)
+        if (typeof command !== "string" || !COMMAND_WORDS.test(command))
+            invalid(`provider ${named} opens a ${kind} with command words, not ${JSON.stringify(command)}`);
+    return Object.fromEntries(known);
+};
 /** An entry as a CLI or the store gives it, checked: anything else is a `validation_error`. */
 export const providerEntryOf = (value) => {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return invalid("a provider entry is an object");
-    const { name, kind, aliases = [], command } = value;
+    const { name, kind, aliases = [], command, opens } = value;
     const named = wordOf(name, "a provider's name");
     if (typeof kind !== "string" || !KINDS.includes(kind))
         invalid(`provider ${named}'s kind is one of ${KINDS.join(", ")} — not ${JSON.stringify(kind)}`);
@@ -73,6 +87,7 @@ export const providerEntryOf = (value) => {
         kind: kind,
         aliases: [...new Set(aliases.map((alias) => wordOf(alias, `an alias of ${named}`)))],
         ...(command === undefined ? {} : { command: wordOf(command, `the command of ${named}`) }),
+        ...(opens === undefined ? {} : { opens: opensOf(opens, named) }),
     };
 };
 const describe = ({ name, kind, command }) => `${name} (${kind}${command ? `, from ${command}` : ""})`;
@@ -87,6 +102,7 @@ const joined = (known, entry) => {
             ...same,
             aliases: [...new Set([...same.aliases, ...entry.aliases])],
             ...(entry.command ? { command: entry.command } : {}),
+            ...(entry.opens ? { opens: { ...same.opens, ...entry.opens } } : {}),
         }
         : entry;
     const others = known.filter((one) => one !== same);

package/dist/domain/ref-arguments.js

@@ -5,18 +5,14 @@ const TAKES = {
     chat: "a chat: chat:<provider>/<account>/<chat>, its id or its title",
     message: "a message: msg:<provider>/<account>/<chat>/<message>, or a chat and the message's id",
 };
-const OPENS = {
-    chat: "messages list",
-    message: "messages show",
-    contact: "contacts show",
-};
 const article = (word) => (/^[aeiou]/.test(word) ? "an" : "a");
 const wrongKind = (text, kind, takes) => new CliError("validation_error", `${text} names ${article(kind)} ${kind}; this takes ${TAKES[takes]}`, {
     reason: "ref.wrong-kind",
 });
 const wrongProvider = (text, provider, kind) => {
-    const command = providerNamed(provider)?.command;
-    const opens = OPENS[kind];
+    const entry = providerNamed(provider);
+    const command = entry?.command;
+    const opens = kind === "entity" ? undefined : entry?.opens?.[kind];
     const how = command && opens ? `open it with ${command} <profile> ${opens} ${text}` : "open it with its own CLI";
     const label = providerLabel(provider);
     return new CliError("validation_error", `${text} is ${article(label.toLowerCase())} ${label} ${kind}; ${how}`, {

package/dist/domain/ref-summaries.d.ts

@@ -0,0 +1,56 @@
+import type { RefKindName } from "./references.js";
+export type RefState = "available" | "deleted" | "unavailable";
+/** A message or chat of the `email` provider is mail, so it reads as `email` and `email_thread`. */
+export type RefSummaryKind = RefKindName | "email" | "email_thread" | "unknown";
+/** What a reference names, read from the store in one batch so a page of refs costs one query per kind. */
+export interface RefSummary {
+    /** Canonical spelling; the map key is the text the caller passed. */
+    ref: string;
+    kind: RefSummaryKind;
+    /** One line, at most 120 characters, never a message body. `null` when the store has no title. */
+    title: string | null;
+    /** What holds it, one line: a message's chat title, a task's project, a document's provider label. */
+    in: string | null;
+    /** ISO 8601 UTC. */
+    at: string | null;
+    provider: string | null;
+    /** The external id of the account that holds it, for `ProfilesFor`; `null` when it belongs to no account. */
+    account: string | null;
+    /** The CLI that opens it (`max`, `tg`, `drive`); `null` when no CLI has registered the provider. */
+    tool: string | null;
+    state: RefState;
+    /** Only with `{ excerpt: true }`: at most 280 characters of the body. */
+    excerpt?: string | null;
+}
+export interface RefsStore {
+    /** One query per kind present. Never throws for a bad ref: it comes back `unknown`, `unavailable`. */
+    summaries(refs: readonly string[], options?: {
+        excerpt?: boolean;
+    }): Promise<Map<string, RefSummary>>;
+}
+/** The caller's answer to "which profile opens this": one signed in, or the choices and why there is not one. */
+export type ProfilesFor = (provider: string, account: string | null) => {
+    profile: string;
+} | {
+    why: string;
+    profiles: string[];
+};
+export interface RefOpen {
+    /** Ready to run; contains `<profile>` when `profiles` is not exactly one. `null` when no CLI opens it. */
+    argv: string[] | null;
+    profiles: string[];
+    why: string | null;
+}
+export declare const PROFILE_PLACEHOLDER = "<profile>";
+/** A title from someone else's text, as one line: a newline in it would break every row it is printed in. */
+export declare const oneLine: (text: string) => string;
+/**
+ * The command that opens a ref. A registered provider opens its own kinds; anything else opens with the caller's
+ * `local` words (memo's `notes show`). The profile is never picked: with none or several, `argv` keeps `<profile>`.
+ */
+export declare const openOf: (summary: RefSummary, ports: {
+    profilesFor: ProfilesFor;
+    local?: Partial<Record<RefKindName, string[]>>;
+}) => RefOpen;
+/** `Chat «Сайт + автоматизация» (MAX)`: the one label every review row, status line and `show` prints. */
+export declare const refLabel: (summary: RefSummary) => string;

package/dist/domain/ref-summaries.js

@@ -0,0 +1,63 @@
+import { singleLine } from "@wirecat/cli-base";
+import { providerNamed } from "./providers.js";
+export const PROFILE_PLACEHOLDER = "<profile>";
+/** A title from someone else's text, as one line: a newline in it would break every row it is printed in. */
+export const oneLine = (text) => singleLine(text.replace(/\s+/g, " ").trim());
+/** Mail is a message and a chat to the provider registry: `opens` is keyed by the reference kind. */
+const openKind = (kind) => kind === "email" ? "message" : kind === "email_thread" ? "chat" : kind === "unknown" ? undefined : kind;
+/**
+ * The command that opens a ref. A registered provider opens its own kinds; anything else opens with the caller's
+ * `local` words (memo's `notes show`). The profile is never picked: with none or several, `argv` keeps `<profile>`.
+ */
+export const openOf = (summary, ports) => {
+    const kind = openKind(summary.kind);
+    if (kind === undefined)
+        return { argv: null, profiles: [], why: `${summary.ref} is not a reference` };
+    const entry = summary.provider === null ? undefined : providerNamed(summary.provider);
+    const words = entry?.command === undefined ? undefined : entry.opens?.[kind];
+    if (entry?.command !== undefined && words !== undefined && summary.provider !== null) {
+        const command = [...words.split(" "), summary.ref];
+        const asked = ports.profilesFor(summary.provider, summary.account);
+        return "profile" in asked
+            ? { argv: [entry.command, asked.profile, ...command], profiles: [asked.profile], why: null }
+            : { argv: [entry.command, PROFILE_PLACEHOLDER, ...command], profiles: asked.profiles, why: asked.why };
+    }
+    const local = ports.local?.[kind];
+    if (local !== undefined)
+        return { argv: [...local, summary.ref], profiles: [], why: null };
+    return {
+        argv: null,
+        profiles: [],
+        why: summary.provider === null
+            ? `nothing here opens a ${kind}`
+            : `no CLI has registered ${summary.provider} in this store yet; run its CLI once`,
+    };
+};
+const WORDS = {
+    message: "Message",
+    chat: "Chat",
+    contact: "Contact",
+    folder: "Folder",
+    meeting: "Meeting",
+    event: "Event",
+    note: "Note",
+    document: "Document",
+    person: "Person",
+    organization: "Organization",
+    project: "Project",
+    task: "Task",
+    memory: "Memory",
+    fact: "Fact",
+    bot: "Bot",
+    email: "Email",
+    email_thread: "Email thread",
+    unknown: "Unknown",
+};
+/** `Chat «Сайт + автоматизация» (MAX)`: the one label every review row, status line and `show` prints. */
+export const refLabel = (summary) => {
+    const named = summary.title === null ? summary.ref : `«${oneLine(summary.title)}»`;
+    const notes = [summary.in === null ? null : oneLine(summary.in), summary.state === "available" ? null : summary.state]
+        .filter((one) => one !== null)
+        .join(", ");
+    return `${WORDS[summary.kind]} ${named}${notes === "" ? "" : ` (${notes})`}`;
+};

package/dist/entities/index.d.ts

@@ -4911,6 +4911,7 @@ export declare const ENTITIES: {
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -4925,6 +4926,7 @@ export declare const ENTITIES: {
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -5023,6 +5025,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5037,6 +5040,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5136,6 +5140,7 @@ export declare const ENTITIES: {
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -5150,6 +5155,7 @@ export declare const ENTITIES: {
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -5277,6 +5283,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5291,6 +5298,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5383,6 +5391,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5397,6 +5406,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -6600,6 +6610,7 @@ export declare const ENTITIES: {
         readonly to: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
         readonly kind: v.PicklistSchema<readonly ["member-of", "related-to"], undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;

package/dist/entities/relationship.d.ts

@@ -6,6 +6,8 @@ export declare const relationship: v.StrictObjectSchema<{
     readonly to: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
     readonly kind: v.PicklistSchema<readonly ["member-of", "related-to"], undefined>;
     readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** A purpose from memo's config; `null` means `work`. */
+    readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     /** An agent's suggestion stays unconfirmed, and `weak`, until the owner confirms it. */
     readonly confirmed: v.BooleanSchema<undefined>;

package/dist/entities/relationship.js

@@ -8,6 +8,8 @@ export const relationship = v.strictObject({
     to: reference,
     kind: v.picklist(RELATION_KINDS),
     role: v.nullable(text),
+    /** A purpose from memo's config; `null` means `work`. */
+    purpose: v.nullable(text),
     evidence: v.nullable(text),
     /** An agent's suggestion stays unconfirmed, and `weak`, until the owner confirms it. */
     confirmed: v.boolean(),

package/dist/entities/task-results.d.ts

@@ -53,6 +53,7 @@ export declare const taskCard: v.StrictObjectSchema<{
         readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
         readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
@@ -67,6 +68,7 @@ export declare const taskCard: v.StrictObjectSchema<{
         readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
         readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
@@ -165,6 +167,7 @@ export declare const taskCreated: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -179,6 +182,7 @@ export declare const taskCreated: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -278,6 +282,7 @@ export declare const taskLinks: v.UnionSchema<[v.StrictObjectSchema<{
         readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
         readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
@@ -292,6 +297,7 @@ export declare const taskLinks: v.UnionSchema<[v.StrictObjectSchema<{
         readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
         readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
@@ -419,6 +425,7 @@ export declare const taskMerge: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -433,6 +440,7 @@ export declare const taskMerge: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -525,6 +533,7 @@ export declare const taskUnmerge: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -539,6 +548,7 @@ export declare const taskUnmerge: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;

package/dist/entities/task-results.js

@@ -15,6 +15,7 @@ const link = v.strictObject({
     origin: v.picklist(LINK_SOURCES),
     target_text: v.nullable(text),
     role: v.nullable(text),
+    purpose: v.nullable(text),
     evidence: v.nullable(text),
     provenance: v.nullable(text),
     confirmed: v.boolean(),

package/dist/errors/reasons.js

@@ -50,6 +50,7 @@ const OTHERS = [
     validation("extraction.text-too-long", "the text is too long for memory extraction"),
     validation("file.locked", "another process holds the file's lock"),
     ["mail.source-failed", "provider_error", "the mail server refused or did not complete a request"],
+    ["mail.search-refused", "provider_error", "the mail server refused to search a folder"],
     ["mirror.partial", "provider_error", "some mirrored files were not synced"],
     ["profile.wrong-account", "authentication_error", "the signed-in source account does not match this profile"],
     validation("push.too-many-files", "the folder holds more files than one push takes"),
@@ -144,6 +145,7 @@ const OTHERS = [
     ],
     validation("name.invalid", "the name is not valid"),
     validation("output.choose-fields", "at a terminal, --json names the fields it prints"),
+    validation("output.conflict", "two output switches ask for different output"),
     validation("output.one-object", "a report is one JSON object; --jsonl streams lists only"),
     validation("output.unknown-field", "the answer has no field by that name"),
     validation("name.taken", "the name is already used"),

package/dist/mail/partial.d.ts

@@ -6,16 +6,22 @@ import type { MailSource } from "./source.js";
 export declare const PARTIAL = "partial";
 /** How many partial emails one sync reads whole at most; the rest wait for the next run. */
 export declare const PARTIAL_PER_RUN = 100;
+/** Failed reads after which a partial email is given up on (`partial.stuck`) and stays as it is. */
+export declare const PARTIAL_TRIES = 3;
 export interface PartialOutcome {
     /** Read whole this run, the mark cleared. */
     completed: number;
-    /** Still partial after this run. */
+    /** Still partial after this run, tried again by the next. */
     left: number;
+    /** Given up on: the server no longer gives this email at its stored place. They stay readable as they are. */
+    stuck: number;
 }
 /**
  * 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 declare const completePartial: ({ store, source, accountId, address, folders, maxBodyChars, maxAttachmentChars, loadEngine, now, take, signal, }: {
     store: MessageStore;

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;