@wirecat/cli-core 0.561.0 → 0.563.0

package/dist/cli/settings.js

@@ -1,7 +1,7 @@
 import { existsSync } from "node:fs";
 import { CliError, configFilePath, resolvePaths, saveConfigFile } from "@wirecat/cli-base";
 import * as v from "valibot";
-import { AI_ENTRIES, resolveAISettings } from "../analysis/settings.js";
+import { AI_DEFAULTS, AI_ENTRIES, resolveAISettings } from "../analysis/settings.js";
 import { parseDuration } from "../domain/duration.js";
 import { DEFAULT_RERANK_MODEL, RERANK_MODELS } from "../embeddings/models.js";
 import { envName, readOnlyLockOf } from "../ports/app.js";
@@ -14,6 +14,7 @@ import { checkConfigText, issueMessage, readConfigFile, readConfigText, savedPer
 import { DEFAULT_CONFIG, ensureDefaultConfig } from "./default-config.js";
 import { profilesHere } from "./messenger/accounts.js";
 import { usableProfileName } from "./profile.js";
+import { withSettingDefaults } from "./setting-defaults.js";
 import { permissionCeiling } from "./setup-answers.js";
 const DEFAULT_LIMIT = DEFAULT_CONFIG.defaults.limit;
 const DEFAULT_KEEP_RUNS_FOR_DAYS = DEFAULT_CONFIG.defaults.keep_runs_for_days;
@@ -107,6 +108,70 @@ const SHARED_DEFAULTS_ONLY = {
     update_check: v.optional(flag),
     skill_hint: v.optional(flag),
 };
+/**
+ * Written into the file's `defaults` at the value the code applies when the file says nothing (WC-CMD-30). Left out:
+ * objects, and settings whose absence means something no value says (`timeout_ms`, `color`, `requests_per_minute`,
+ * the embedding model), since writing any value would change what they do.
+ */
+const SHARED_SETTINGS = [
+    { key: "limit", default: DEFAULT_LIMIT, description: "how many items a list shows at once" },
+    { key: "keep_runs_for_days", default: DEFAULT_KEEP_RUNS_FOR_DAYS, description: "days a run is kept" },
+    {
+        key: "sends_per_hour",
+        default: DEFAULT_SENDS_PER_HOUR,
+        description: "the most messages an account sends in an hour; a bot has none unless its section sets one",
+    },
+    { key: "update_check", default: true, description: "check once a day for a newer version" },
+    {
+        key: "skill_hint",
+        default: true,
+        description: "tell an agent once a day that `skill install` would give it this tool's guide",
+    },
+    { key: "record", default: true, description: "keep every run in runs list; false keeps failed runs only" },
+    {
+        key: "record_input",
+        default: true,
+        description: 'keep what was typed in a run\'s command line: true, false, or "failed" for failed runs only',
+    },
+    {
+        key: "keep_successful_runs_for_days",
+        default: KEEP_SUCCESSFUL_RUNS_FOR_DAYS,
+        description: "days a successful run is kept",
+    },
+    { key: "runs_size_limit_mb", default: RUNS_SIZE_LIMIT_MB, description: "the most megabytes all runs may take" },
+    { key: "sender_colors", default: false, description: "color each sender's name in a conversation" },
+    { key: "search_catch_up", default: false, description: "prepare local search after a gaps repair" },
+    {
+        key: "history_dialog_days",
+        default: DEFAULT_HISTORY_LIMITS.dialogDays,
+        description: "days of a one-to-one chat's pushed history the store keeps",
+    },
+    {
+        key: "history_group_days",
+        default: DEFAULT_HISTORY_LIMITS.groupDays,
+        description: "days of a group's pushed history the store keeps",
+    },
+    {
+        key: "history_group_members_max",
+        default: DEFAULT_HISTORY_LIMITS.groupMembersMax,
+        description: "a group with more people than this keeps no pushed history",
+    },
+    {
+        key: "picture_search",
+        default: false,
+        description: "search and images embed read the pictures themselves, with a model on this computer",
+    },
+    {
+        key: "search_reranker",
+        default: DEFAULT_RERANK_MODEL,
+        description: "the reranker that orders search's first hits, or off",
+    },
+    {
+        key: "embedding_provider",
+        default: AI_DEFAULTS.embeddingProvider,
+        description: "local or openai: what turns text into vectors for search by meaning",
+    },
+];
 /** Where `profile` came from when none was named and the command needs none. */
 export const NONE_NAMED = "none named";
 /** A name for a command that speaks for no account; never chosen for one that does. */
@@ -174,12 +239,18 @@ export const settingsFor = (app, extension = {}) => {
     const allSettings = [...Object.keys(profileEntries), ...botOnlyKeys, ...defaultsOnlyKeys].filter((setting) => app.messenger !== false ||
         !MESSENGER_ONLY_SETTINGS.includes(setting) ||
         (app.sends === true && setting === "sends_per_hour"));
+    const readSchema = extension.schema ?? schema;
+    // An app with a schema of its own may refuse a shared key in `defaults`; writing it would break that file.
+    const declaredSettings = [...SHARED_SETTINGS, ...(extension.settings ?? [])]
+        .filter(({ key, default: value }) => allSettings.includes(key) && v.safeParse(readSchema, { defaults: { [key]: value } }).success)
+        .map((setting) => ({ ...setting, key: `defaults.${setting.key}` }));
+    // `defaults` needs no field of its own, so it is the one section created: every key then shows (RISK-2125).
+    const withDefaults = (raw, except = []) => withSettingDefaults(isScope(raw) && !Object.hasOwn(raw, "defaults") ? { ...raw, defaults: {} } : raw, declaredSettings.filter(({ key }) => !except.includes(key)));
     const PROFILE = envName(app, "PROFILE");
     const PROFILE_LOCK = envName(app, "PROFILE_LOCK");
     const TIMEOUT = envName(app, "TIMEOUT");
     const REQUESTS_PER_MINUTE = envName(app, "REQUESTS_PER_MINUTE");
     const configPathFor = ({ env = process.env, configDir }) => configFilePath(configDir ?? resolvePaths({ appName: app.appName, prefix: app.envPrefix, env }).config);
-    const readSchema = extension.schema ?? schema;
     const context = (file) => ({ file, tool: app.command });
     /** The file with every problem found; what loads is the file without the settings they name. */
     const loadConfig = (path) => {
@@ -225,7 +296,7 @@ export const settingsFor = (app, extension = {}) => {
         const configPath = configPathFor(options);
         try {
             if (!options.readOnly)
-                ensureDefaultConfig(configPath);
+                ensureDefaultConfig(configPath, withDefaults(DEFAULT_CONFIG).config);
         }
         catch (error) {
             throw new CliError("configuration_error", error instanceof Error ? error.message : String(error));
@@ -435,7 +506,7 @@ export const settingsFor = (app, extension = {}) => {
                 throw new CliError("validation_error", `${setting} has no problem to remove — name the profile, or add --defaults, to unset a setting`);
             if (!known && valueAt(raw, at) === undefined)
                 throw new CliError("validation_error", `no setting called "${setting}" — one of: ${allSettings.join(", ")}`);
-            saveConfigFile(path, withoutPath(raw, at).config);
+            saveConfigFile(path, withDefaults(withoutPath(raw, at).config, [at.join(".")]).config);
             return null;
         }
         if (!known)
@@ -456,13 +527,25 @@ export const settingsFor = (app, extension = {}) => {
         if (added)
             throw new CliError("validation_error", `${setting} cannot be "${value}": ${added.what}`);
         const checked = v.safeParse(readSchema, changed);
-        saveConfigFile(path, checked.success ? checked.output : changed);
+        saveConfigFile(path, withDefaults(checked.success ? checked.output : changed).config);
         return valueAt(checked.success ? checked.output : changed, at) ?? null;
     };
+    /** Each declared setting the file lacks, at its default, on the file as written; the keys added. */
+    const migrate = (path) => {
+        const read = readConfigFile(path);
+        if ("issue" in read)
+            throw new CliError("configuration_error", issueMessage([read.issue]));
+        const { config, added } = withDefaults(read.raw);
+        if (added.length > 0)
+            saveConfigFile(path, config);
+        return added;
+    };
     return {
         resolveSettings,
         configuredProfiles,
         changeSetting,
+        migrate,
+        declaredSettings,
         allSettings,
         defaultsOnlyKeys,
         schema,

package/dist/cli/shared-command-exports.d.ts

@@ -8,6 +8,8 @@ export declare const appDoctorCommand: (app: import("./entry.js").AppIdentity, c
         kind?: import("./settings.js").ProfileKind | undefined;
         root?: boolean;
     }) => unknown;
+    migrate: (path: string) => string[];
+    declaredSettings: import("./setting-defaults.js").DeclaredSetting[];
     allSettings: string[];
     defaultsOnlyKeys: string[];
     schema: import("valibot").StrictObjectSchema<{
@@ -188,6 +190,8 @@ export declare const appMcpCommand: (app: import("./entry.js").AppIdentity, conf
         kind?: import("./settings.js").ProfileKind | undefined;
         root?: boolean;
     }) => unknown;
+    migrate: (path: string) => string[];
+    declaredSettings: import("./setting-defaults.js").DeclaredSetting[];
     allSettings: string[];
     defaultsOnlyKeys: string[];
     schema: import("valibot").StrictObjectSchema<{
@@ -375,6 +379,8 @@ export declare const configCommand: (app: import("./entry.js").AppIdentity, conf
         kind?: import("./settings.js").ProfileKind | undefined;
         root?: boolean;
     }) => unknown;
+    migrate: (path: string) => string[];
+    declaredSettings: import("./setting-defaults.js").DeclaredSetting[];
     allSettings: string[];
     defaultsOnlyKeys: string[];
     schema: import("valibot").StrictObjectSchema<{
@@ -590,6 +596,8 @@ export declare const completeCommand: (messenger: import("./index.js").Messenger
         kind?: import("./settings.js").ProfileKind | undefined;
         root?: boolean;
     }) => unknown;
+    migrate: (path: string) => string[];
+    declaredSettings: import("./setting-defaults.js").DeclaredSetting[];
     allSettings: string[];
     defaultsOnlyKeys: string[];
     schema: import("valibot").StrictObjectSchema<{

package/dist/domain/admin-statistics.d.ts

@@ -75,4 +75,9 @@ export interface AdminCalculated {
     graph: ReturnType<typeof rankReplyGraph>["quality"];
 }
 export declare const adminEntityKey: (row: Pick<AdminRow, "account" | "id">) => string;
+/** Median and nearest-rank p90 of reply delays, the numbers every response-time answer reports. */
+export declare const delayStats: (delays: number[]) => {
+    medianMilliseconds: number | null;
+    p90Milliseconds: number | null;
+};
 export declare const calculateAdminStatistics: (nodes: AdminNode[], stays: AdminStay[], options: AdminOptions, inspect: () => void) => AdminCalculated;

package/dist/domain/admin-statistics.js

@@ -6,7 +6,8 @@ import { rankingQuestion } from "./rankings-options.js";
 export const adminEntityKey = (row) => JSON.stringify([row.account.provider, row.account.account, row.id]);
 const personKey = (node) => JSON.stringify([node.account.provider, node.account.account, node.sender]);
 const locator = (node) => formatLocator({ ...node.account, chat: node.chatId, message: node.id });
-const stats = (delays) => {
+/** Median and nearest-rank p90 of reply delays, the numbers every response-time answer reports. */
+export const delayStats = (delays) => {
     const sorted = delays.toSorted((a, b) => a - b);
     const middle = Math.floor(sorted.length / 2);
     return {
@@ -103,7 +104,7 @@ export const calculateAdminStatistics = (nodes, stays, options, inspect) => {
                 account: { provider: person.provider, account: person.account },
                 questions: eligible.filter((node) => node.account.provider === person.provider && node.account.account === person.account).length,
                 answered: rows.length,
-                ...stats(rows.map((row) => row.contribution)),
+                ...delayStats(rows.map((row) => row.contribution)),
                 status: "observed",
             }, rows);
         }
@@ -154,7 +155,7 @@ export const calculateAdminStatistics = (nodes, stays, options, inspect) => {
                 pending: end > options.cutoff,
                 questions: held.length,
                 answered: delays.length,
-                ...stats(delays),
+                ...delayStats(delays),
                 status: "partial",
             }, contributions);
         }

package/dist/entities/index.d.ts

@@ -71,6 +71,7 @@ import { reactionChange } from "./reaction-change.js";
 import { recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved } from "./recipient.js";
 import { recordedRun, runDetails, runHit, runLocation } from "./recorded-run.js";
 import { relationship } from "./relationship.js";
+import { responseTimes, waitingChats } from "./reply-stats.js";
 import { retention } from "./retention.js";
 import { savedSearch, searchHistoryClear } from "./saved-search.js";
 import { sendAttempt } from "./send-attempt.js";
@@ -88,7 +89,7 @@ import { topic } from "./topic.js";
  * subset of its fields, never a renamed one. Commands move onto these one by one; until then, a schema
  * is the target, not a description of today's output.
  */
-export { account, accountChange, accountPrivacy, accountPrivacyChange, accountProfile, accountSession, adminReport, agenda, analysisConsent, analysisConsentRevocation, attachment, attachmentBytes, attachmentExtraction, attachmentTextChange, automaticTags, botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, cachedChatMetadata, callRecord, chart, chat, chatAdminChange, chatArchive, chatEvent, chatFolderChange, chatFolderOrder, chatFolderRemoval, chatGroupChange, chatInspection, chatInvite, chatInviteChange, chatMembersChange, chatMembersFetch, chatMetadata, chatMetadataRefresh, chatModeration, chatMuting, chatPin, chatRead, chatRemoval, chatRequestChange, chatRules, chatSender, chatStats, chatTracking, chatUnread, contact, contactActivity, contactAlias, contactCheck, contactContext, contactImport, contactLookup, contactNote, contactNoteRemoval, contactPreparation, contactStateChange, contactSync, contactUpdate, conversation, conversationBatch, conversationBatchStatus, conversationBuildResult, conversationChange, conversationDetails, conversationEmbedding, conversationEmbeddingStatus, conversationHit, conversationPreparation, conversationReadiness, counterRefresh, counters, document, documentLink, endedAccountSessions, evidence, evidencePacket, fact, folder, hit, identity, imageEmbedding, inviteLink, job, joinRequest, linkedPerson, mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer, meeting, meetingProjectCandidates, meetingSeriesInventory, member, memory, mention, mentionDecision, mentionDetails, mentionDomain, mentionRebuild, message, messageContext, messageCounts, messageDeletion, messageDownload, messageEvent, messageLink, messageLinks, messagePin, messageStar, messageSync, messageTranscript, messageWrite, model, modelKey, note, officialStats, organization, person, place, poll, pollChange, pollVote, project, ranking, reaction, reactionChange, recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved, recordedRun, reference, relationship, reminder, removedModelKey, retention, runDetails, runHit, runLocation, savedSearch, scheduledJob, searchHistoryClear, sendAttempt, serveSummary, stickerInventory, storeBackup, storeChatStatus, storeCheck, storeClear, storeCopyRemoval, storeDecrypt, storedModelKey, storeExport, storeGapPlan, storeGapRepair, storeInfo, storeJobCancel, storeJobClear, storeJobDetails, storeJobRetry, storeMigration, storeReindex, storeRepair, storeReset, storeRestore, storeTable, tagChange, tagging, task, taskAnalysis, taskAnalysisMark, taskCard, taskCategories, taskClosed, taskCreated, taskLinks, taskMerge, taskPair, taskScan, taskSimilar, taskStats, taskUnmerge, topic, topicIcon, trackedChat, trackedChatHistory, watchedMessage, watchItem, };
+export { account, accountChange, accountPrivacy, accountPrivacyChange, accountProfile, accountSession, adminReport, agenda, analysisConsent, analysisConsentRevocation, attachment, attachmentBytes, attachmentExtraction, attachmentTextChange, automaticTags, botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, cachedChatMetadata, callRecord, chart, chat, chatAdminChange, chatArchive, chatEvent, chatFolderChange, chatFolderOrder, chatFolderRemoval, chatGroupChange, chatInspection, chatInvite, chatInviteChange, chatMembersChange, chatMembersFetch, chatMetadata, chatMetadataRefresh, chatModeration, chatMuting, chatPin, chatRead, chatRemoval, chatRequestChange, chatRules, chatSender, chatStats, chatTracking, chatUnread, contact, contactActivity, contactAlias, contactCheck, contactContext, contactImport, contactLookup, contactNote, contactNoteRemoval, contactPreparation, contactStateChange, contactSync, contactUpdate, conversation, conversationBatch, conversationBatchStatus, conversationBuildResult, conversationChange, conversationDetails, conversationEmbedding, conversationEmbeddingStatus, conversationHit, conversationPreparation, conversationReadiness, counterRefresh, counters, document, documentLink, endedAccountSessions, evidence, evidencePacket, fact, folder, hit, identity, imageEmbedding, inviteLink, job, joinRequest, linkedPerson, mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer, meeting, meetingProjectCandidates, meetingSeriesInventory, member, memory, mention, mentionDecision, mentionDetails, mentionDomain, mentionRebuild, message, messageContext, messageCounts, messageDeletion, messageDownload, messageEvent, messageLink, messageLinks, messagePin, messageStar, messageSync, messageTranscript, messageWrite, model, modelKey, note, officialStats, organization, person, place, poll, pollChange, pollVote, project, ranking, reaction, reactionChange, recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved, recordedRun, reference, relationship, reminder, removedModelKey, responseTimes, retention, runDetails, runHit, runLocation, savedSearch, scheduledJob, searchHistoryClear, sendAttempt, serveSummary, stickerInventory, storeBackup, storeChatStatus, storeCheck, storeClear, storeCopyRemoval, storeDecrypt, storedModelKey, storeExport, storeGapPlan, storeGapRepair, storeInfo, storeJobCancel, storeJobClear, storeJobDetails, storeJobRetry, storeMigration, storeReindex, storeRepair, storeReset, storeRestore, storeTable, tagChange, tagging, task, taskAnalysis, taskAnalysisMark, taskCard, taskCategories, taskClosed, taskCreated, taskLinks, taskMerge, taskPair, taskScan, taskSimilar, taskStats, taskUnmerge, topic, topicIcon, trackedChat, trackedChatHistory, waitingChats, watchedMessage, watchItem, };
 export declare const ENTITIES: {
     readonly meeting_ingestion: v.StrictObjectSchema<{
         readonly meetings: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
@@ -10860,6 +10861,35 @@ export declare const ENTITIES: {
             readonly count: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
         }, undefined>, undefined>;
     }, undefined>;
+    readonly response_times: v.StrictObjectSchema<{
+        readonly replies: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly median_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly p90_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly mean_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly who: v.PicklistSchema<["me", "others"], undefined>;
+        readonly buckets: v.StrictObjectSchema<{
+            readonly under_5m: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly under_1h: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly under_1d: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly over_1d: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        }, undefined>;
+        readonly rows: v.ArraySchema<v.StrictObjectSchema<{
+            readonly replies: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly median_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+            readonly p90_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+            readonly mean_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+            readonly key: v.StringSchema<undefined>;
+        }, undefined>, undefined>;
+    }, undefined>;
+    readonly waiting_chats: v.StrictObjectSchema<{
+        readonly chats: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly messages: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly oldest_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+        readonly by_kind: v.StrictObjectSchema<{
+            readonly private: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+            readonly group: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        }, undefined>;
+    }, undefined>;
     readonly ranking: v.StrictObjectSchema<{
         readonly target: v.PicklistSchema<["messages", "contacts"], undefined>;
         readonly measure: v.StringSchema<undefined>;

package/dist/entities/index.js

@@ -78,6 +78,7 @@ import { reactionChange } from "./reaction-change.js";
 import { recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved } from "./recipient.js";
 import { recordedRun, runDetails, runHit, runLocation } from "./recorded-run.js";
 import { relationship } from "./relationship.js";
+import { responseTimes, waitingChats } from "./reply-stats.js";
 import { retention } from "./retention.js";
 import { savedSearch, searchHistoryClear } from "./saved-search.js";
 import { sendAttempt } from "./send-attempt.js";
@@ -95,7 +96,7 @@ import { topic } from "./topic.js";
  * subset of its fields, never a renamed one. Commands move onto these one by one; until then, a schema
  * is the target, not a description of today's output.
  */
-export { account, accountChange, accountPrivacy, accountPrivacyChange, accountProfile, accountSession, adminReport, agenda, analysisConsent, analysisConsentRevocation, attachment, attachmentBytes, attachmentExtraction, attachmentTextChange, automaticTags, botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, cachedChatMetadata, callRecord, chart, chat, chatAdminChange, chatArchive, chatEvent, chatFolderChange, chatFolderOrder, chatFolderRemoval, chatGroupChange, chatInspection, chatInvite, chatInviteChange, chatMembersChange, chatMembersFetch, chatMetadata, chatMetadataRefresh, chatModeration, chatMuting, chatPin, chatRead, chatRemoval, chatRequestChange, chatRules, chatSender, chatStats, chatTracking, chatUnread, contact, contactActivity, contactAlias, contactCheck, contactContext, contactImport, contactLookup, contactNote, contactNoteRemoval, contactPreparation, contactStateChange, contactSync, contactUpdate, conversation, conversationBatch, conversationBatchStatus, conversationBuildResult, conversationChange, conversationDetails, conversationEmbedding, conversationEmbeddingStatus, conversationHit, conversationPreparation, conversationReadiness, counterRefresh, counters, document, documentLink, endedAccountSessions, evidence, evidencePacket, fact, folder, hit, identity, imageEmbedding, inviteLink, job, joinRequest, linkedPerson, mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer, meeting, meetingProjectCandidates, meetingSeriesInventory, member, memory, mention, mentionDecision, mentionDetails, mentionDomain, mentionRebuild, message, messageContext, messageCounts, messageDeletion, messageDownload, messageEvent, messageLink, messageLinks, messagePin, messageStar, messageSync, messageTranscript, messageWrite, model, modelKey, note, officialStats, organization, person, place, poll, pollChange, pollVote, project, ranking, reaction, reactionChange, recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved, recordedRun, reference, relationship, reminder, removedModelKey, retention, runDetails, runHit, runLocation, savedSearch, scheduledJob, searchHistoryClear, sendAttempt, serveSummary, stickerInventory, storeBackup, storeChatStatus, storeCheck, storeClear, storeCopyRemoval, storeDecrypt, storedModelKey, storeExport, storeGapPlan, storeGapRepair, storeInfo, storeJobCancel, storeJobClear, storeJobDetails, storeJobRetry, storeMigration, storeReindex, storeRepair, storeReset, storeRestore, storeTable, tagChange, tagging, task, taskAnalysis, taskAnalysisMark, taskCard, taskCategories, taskClosed, taskCreated, taskLinks, taskMerge, taskPair, taskScan, taskSimilar, taskStats, taskUnmerge, topic, topicIcon, trackedChat, trackedChatHistory, watchedMessage, watchItem, };
+export { account, accountChange, accountPrivacy, accountPrivacyChange, accountProfile, accountSession, adminReport, agenda, analysisConsent, analysisConsentRevocation, attachment, attachmentBytes, attachmentExtraction, attachmentTextChange, automaticTags, botAdmin, botMenuEntry, botProfile, botSeenChat, botTemplate, botWebhook, cachedChatMetadata, callRecord, chart, chat, chatAdminChange, chatArchive, chatEvent, chatFolderChange, chatFolderOrder, chatFolderRemoval, chatGroupChange, chatInspection, chatInvite, chatInviteChange, chatMembersChange, chatMembersFetch, chatMetadata, chatMetadataRefresh, chatModeration, chatMuting, chatPin, chatRead, chatRemoval, chatRequestChange, chatRules, chatSender, chatStats, chatTracking, chatUnread, contact, contactActivity, contactAlias, contactCheck, contactContext, contactImport, contactLookup, contactNote, contactNoteRemoval, contactPreparation, contactStateChange, contactSync, contactUpdate, conversation, conversationBatch, conversationBatchStatus, conversationBuildResult, conversationChange, conversationDetails, conversationEmbedding, conversationEmbeddingStatus, conversationHit, conversationPreparation, conversationReadiness, counterRefresh, counters, document, documentLink, endedAccountSessions, evidence, evidencePacket, fact, folder, hit, identity, imageEmbedding, inviteLink, job, joinRequest, linkedPerson, mediaArchive, mediaArchiveCheck, mediaArchiveMove, mediaArchiveTimer, meeting, meetingProjectCandidates, meetingSeriesInventory, member, memory, mention, mentionDecision, mentionDetails, mentionDomain, mentionRebuild, message, messageContext, messageCounts, messageDeletion, messageDownload, messageEvent, messageLink, messageLinks, messagePin, messageStar, messageSync, messageTranscript, messageWrite, model, modelKey, note, officialStats, organization, person, place, poll, pollChange, pollVote, project, ranking, reaction, reactionChange, recipient, recipientAdded, recipientChange, recipientOff, recipientRemoved, recordedRun, reference, relationship, reminder, removedModelKey, responseTimes, retention, runDetails, runHit, runLocation, savedSearch, scheduledJob, searchHistoryClear, sendAttempt, serveSummary, stickerInventory, storeBackup, storeChatStatus, storeCheck, storeClear, storeCopyRemoval, storeDecrypt, storedModelKey, storeExport, storeGapPlan, storeGapRepair, storeInfo, storeJobCancel, storeJobClear, storeJobDetails, storeJobRetry, storeMigration, storeReindex, storeRepair, storeReset, storeRestore, storeTable, tagChange, tagging, task, taskAnalysis, taskAnalysisMark, taskCard, taskCategories, taskClosed, taskCreated, taskLinks, taskMerge, taskPair, taskScan, taskSimilar, taskStats, taskUnmerge, topic, topicIcon, trackedChat, trackedChatHistory, waitingChats, watchedMessage, watchItem, };
 export const ENTITIES = {
     sync_progress: syncProgress,
     ...MEETING_RESULT_ENTITIES,
@@ -348,6 +349,8 @@ export const ENTITIES = {
     topic,
     folder,
     message_counts: messageCounts,
+    response_times: responseTimes,
+    waiting_chats: waitingChats,
     ranking,
     admin_report: adminReport,
     analysis_consent: analysisConsent,

package/dist/entities/reply-stats.d.ts

@@ -0,0 +1,33 @@
+import * as v from "valibot";
+/** How long replies took in one-to-one chats: the owner's (`me`) or the other side's (`others`). */
+export declare const responseTimes: v.StrictObjectSchema<{
+    readonly replies: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly median_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly p90_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly mean_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+    readonly who: v.PicklistSchema<["me", "others"], undefined>;
+    readonly buckets: v.StrictObjectSchema<{
+        readonly under_5m: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly under_1h: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly under_1d: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly over_1d: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>;
+    /** One row per calendar day of the reply; empty with `--by total`. */
+    readonly rows: v.ArraySchema<v.StrictObjectSchema<{
+        readonly replies: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly median_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly p90_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly mean_ms: v.NullableSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 0, undefined>]>, undefined>;
+        readonly key: v.StringSchema<undefined>;
+    }, undefined>, undefined>;
+}, undefined>;
+/** Chats whose newest message asks the owner something, and how much waits there. */
+export declare const waitingChats: v.StrictObjectSchema<{
+    readonly chats: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly messages: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    readonly oldest_at: v.NullableSchema<v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.IsoTimestampAction<string, "an ISO 8601 time in UTC">, v.EndsWithAction<string, "Z", "an ISO 8601 time in UTC, ending in `Z`">]>, undefined>;
+    readonly by_kind: v.StrictObjectSchema<{
+        readonly private: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+        readonly group: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 0, undefined>]>;
+    }, undefined>;
+}, undefined>;

package/dist/entities/reply-stats.js

@@ -0,0 +1,19 @@
+import * as v from "valibot";
+import { count, text, time } from "./fields.js";
+const milliseconds = v.nullable(v.pipe(v.number(), v.minValue(0)));
+const figures = { replies: count, median_ms: milliseconds, p90_ms: milliseconds, mean_ms: milliseconds };
+/** How long replies took in one-to-one chats: the owner's (`me`) or the other side's (`others`). */
+export const responseTimes = v.strictObject({
+    who: v.picklist(["me", "others"]),
+    ...figures,
+    buckets: v.strictObject({ under_5m: count, under_1h: count, under_1d: count, over_1d: count }),
+    /** One row per calendar day of the reply; empty with `--by total`. */
+    rows: v.array(v.strictObject({ key: text, ...figures })),
+});
+/** Chats whose newest message asks the owner something, and how much waits there. */
+export const waitingChats = v.strictObject({
+    chats: count,
+    messages: count,
+    oldest_at: v.nullable(time),
+    by_kind: v.strictObject({ private: count, group: count }),
+});

package/dist/errors/reasons.d.ts

@@ -7,7 +7,7 @@ export declare const REASONS: ErrorReason[];
  * Detail keys an error from this package may carry, until each is registered on its own reason. Not `cause`:
  * that can hold a provider's or SQLite's raw text.
  */
-export declare const DETAILS: readonly ["contracts", "calendars", "allowed", "alternative", "arguments", "at", "available", "batch", "budget", "built", "candidates", "chat", "chat_id", "cli", "column", "complete", "emitted_bytes", "exact", "file", "forum", "guide", "hint", "id", "index", "kind", "limit", "limit_source", "line", "max_bytes", "model", "name", "operation_id", "operation_ids", "text_limit", "store_refused_in", "subtasks", "partial_output", "parent", "path", "permission", "person_ids", "previous_chat_id", "profiles", "provider_error", "provider", "recovery", "reference", "remembered", "retry_at", "retry_after_ms", "runtime", "saved", "scheduled_for", "script", "sent", "sent_count", "settlement_failed", "span", "sqlite", "stage", "standing", "state", "stderr", "term", "total", "upgraded", "wanted"];
+export declare const DETAILS: readonly ["contracts", "calendars", "allowed", "alternative", "arguments", "at", "available", "batch", "budget", "built", "candidates", "chat", "chat_id", "cli", "column", "complete", "emitted_bytes", "exact", "file", "forum", "guide", "hint", "id", "index", "kind", "limit", "limit_source", "line", "max_bytes", "model", "name", "operation_id", "operation_ids", "text_limit", "store_refused_in", "partial_output", "parent", "path", "permission", "person_ids", "previous_chat_id", "profiles", "provider_error", "provider", "recovery", "reference", "remembered", "retry_at", "retry_after_ms", "runtime", "saved", "scheduled_for", "script", "sent", "sent_count", "settlement_failed", "span", "sqlite", "stage", "standing", "state", "stderr", "term", "total", "upgraded", "wanted"];
 /** What a CLI adds to the shared registry: its own reasons, and the detail keys its adapters raise. */
 export interface AppErrors {
     reasons?: readonly ErrorReason[];

package/dist/errors/reasons.js

@@ -47,6 +47,7 @@ const OTHERS = [
     validation("mail-findings.stale", "mail findings cite mail that changed since it was read; stage a new batch"),
     validation("mail-findings.partial", "a cited email is not stored whole yet; cite it once it is"),
     validation("evidence-findings.dedicated-review", "review evidence findings through the dedicated findings command"),
+    validation("mail-findings.dedicated-review", "review mail findings through the dedicated findings command"),
     validation("document.changed", "the document changed while it was read; nothing was saved"),
     ["document.not-imported", "not_found", "the document is not imported in this source account"],
     ["extraction.invalid-proposals", "invalid_response", "the model's memory proposals could not be used"],
@@ -218,8 +219,7 @@ const OTHERS = [
     ["task.stale", "configuration_error", "the task changed since it was read; read it again"],
     validation("task.column", "the task beside which it moves is in another column than the status asked for"),
     validation("task.dependency-cycle", "the task would depend on itself"),
-    validation("task.has-subtasks", "the task has subtasks; move or detach them before it moves to another project"),
-    validation("task.is-subtask", "a subtask moves to another project only when it is detached from its parent in the same write"),
+    validation("task.is-subtask", "a subtask moves to another project alone only when it is detached from its parent in the same write"),
     validation("task.duplicate-candidates", "open tasks may be the same job: attach to one, or add it as new"),
     validation("task.already-read", "the message was already read for tasks: a read again only updates and closes tasks unless --open-new"),
     validation("task.certainty-required", "an agent closes a task with its certainty, 0 to 1"),
@@ -300,7 +300,6 @@ export const DETAILS = [
     "operation_ids",
     "text_limit",
     "store_refused_in",
-    "subtasks",
     "partial_output",
     "parent",
     "path",

package/dist/mail/attachments.d.ts

@@ -3,14 +3,27 @@ import type { AttachmentInput, EmailAddress } from "../store/index.js";
 import type { Address, ParsedMail } from "./parse.js";
 import type { MailSyncResult } from "./sync.js";
 export declare const MAX_ATTACHMENT_CHARS = 200000;
+/** Whether a sync reads an email's attachments into the index, and the largest file it reads. */
+export interface MailAttachmentPolicy {
+    read: boolean;
+    maxBytes: number;
+}
+/** On, up to 10 MB a file: ordinary documents and scans are read, a large archive or video is not. */
+export declare const DEFAULT_ATTACHMENT_POLICY: MailAttachmentPolicy;
+/** Why a policy left an attachment unread; `readEmailWhole` reads it anyway. */
+export declare const POLICY_SKIPS: readonly ["not-read", "too-large"];
 /** One chunk of raw mail is held in memory at a time. */
 export declare const FETCH_CHUNK = 50;
 export declare const addressOf: ({ email, name }: Address) => EmailAddress;
 export type AttachmentLog = NonNullable<MailSyncResult["attachments"]>;
-/** A parsed email's attachments as the store keeps them, each with its text or why it has none. */
-export declare const readAttachments: (mail: ParsedMail, messageId: string, { loadEngine, maxAttachmentChars, at, signal, }: {
+/**
+ * A parsed email's attachments as the store keeps them, each with its text or why it has none. Without `policy` every
+ * attachment is read, whatever its size.
+ */
+export declare const readAttachments: (mail: ParsedMail, messageId: string, { loadEngine, maxAttachmentChars, at, signal, policy, }: {
     loadEngine: LoadEngine;
     maxAttachmentChars: number;
     at: number;
     signal?: AbortSignal;
+    policy?: MailAttachmentPolicy;
 }, log: AttachmentLog) => Promise<AttachmentInput[]>;

package/dist/mail/attachments.js

@@ -1,17 +1,33 @@
 import { extractText } from "../attachments/extract.js";
 export const MAX_ATTACHMENT_CHARS = 200_000;
+/** On, up to 10 MB a file: ordinary documents and scans are read, a large archive or video is not. */
+export const DEFAULT_ATTACHMENT_POLICY = { read: true, maxBytes: 10 * 1024 * 1024 };
+/** Why a policy left an attachment unread; `readEmailWhole` reads it anyway. */
+export const POLICY_SKIPS = ["not-read", "too-large"];
 /** One chunk of raw mail is held in memory at a time. */
 export const FETCH_CHUNK = 50;
 export const addressOf = ({ email, name }) => ({ address: email, name });
-/** A parsed email's attachments as the store keeps them, each with its text or why it has none. */
-export const readAttachments = async (mail, messageId, { loadEngine, maxAttachmentChars, at, signal, }, log) => {
+/**
+ * A parsed email's attachments as the store keeps them, each with its text or why it has none. Without `policy` every
+ * attachment is read, whatever its size.
+ */
+export const readAttachments = async (mail, messageId, { loadEngine, maxAttachmentChars, at, signal, policy, }, log) => {
     const files = [];
     for (const [position, part] of mail.attachments.entries()) {
         if (signal?.aborted)
             throw signal.reason;
+        const skipped = part.bytes === null || policy === undefined
+            ? undefined
+            : !policy.read
+                ? "not-read"
+                : part.bytes.byteLength > policy.maxBytes
+                    ? "too-large"
+                    : undefined;
         const extraction = part.bytes === null
             ? { status: "unavailable" }
-            : await extractText(part.bytes, { kind: "file", name: part.name, mime: part.mime, path: part.name }, loadEngine, signal);
+            : skipped
+                ? { status: skipped }
+                : await extractText(part.bytes, { kind: "file", name: part.name, mime: part.mime, path: part.name }, loadEngine, signal);
         log.push({ message: messageId, part: part.id, status: extraction.status });
         const extracted = extraction.status === "extracted" ? extraction : undefined;
         files.push({

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

@@ -3,7 +3,22 @@ import { type MailServerAccess } from "../../mail/server-search.js";
 import type { AppIdentity } from "../../ports/app.js";
 import { type AccountKey, type MessageStore } from "../../store/store.js";
 export { mailMark, markItem, markText } from "./marks.js";
-export { MAIL_REVIEW_QUERY, MAIL_REVIEW_STEPS } from "./review.js";
+export { MAIL_REVIEW_QUERY, MAIL_REVIEW_STEPS, mailReviewSteps } from "./review.js";
+/**
+ * Where a host mounted `review`, `messages acknowledge` and `conversations show`, and the option that names one
+ * mailbox, so the steps a review hands on run there. A mail CLI leaves it out: its profile names the mailbox.
+ */
+export interface MailMount {
+    review?: string;
+    acknowledge?: string;
+    /** `null`: the host mounts no thread read, so a review offers none. */
+    conversation?: string | null;
+    /** In snake_case, as a step names it: memo's `source`, with `email:<account>`. */
+    mailbox?: {
+        option: string;
+        value: (mailbox: AccountKey) => string;
+    };
+}
 /** What a mail CLI hands the shared commands: how to open the store for one run, and whose mail it reads. */
 export interface MailReads {
     app: AppIdentity;
@@ -14,6 +29,7 @@ export interface MailReads {
     read: <T>(command: Command, work: (store: MessageStore, mailbox: AccountKey) => Promise<T>) => Promise<T>;
     /** The mailbox's server, for `search messages --backend`; without it the search reads the store only. */
     server?: (command: Command) => MailServerAccess;
+    mount?: MailMount;
     /** How `--server-time` help states its default when a provider's own differs (`MailServerAccess.timeMs`). */
     serverTimeDefault?: string;
 }

package/dist/mail/cli/index.js

@@ -21,7 +21,7 @@ import { queryFilter, THREAD_COLUMNS } from "../../store/store.js";
 import { acknowledgeCommand } from "./marks.js";
 import { mailReviewCommand } from "./review.js";
 export { mailMark, markItem, markText } from "./marks.js";
-export { MAIL_REVIEW_QUERY, MAIL_REVIEW_STEPS } from "./review.js";
+export { MAIL_REVIEW_QUERY, MAIL_REVIEW_STEPS, mailReviewSteps } from "./review.js";
 /** A locked or broken store must fail the command, not read as "nothing stored yet". */
 const absentAccount = (error) => {
     if (error instanceof CliError && error.code === "not_found")

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

@@ -1,8 +1,11 @@
+import { type StepDefinition } from "@wirecat/cli-base/standards";
 import { Command } from "commander";
-import type { MailReads } from "./index.js";
+import type { MailMount, MailReads } from "./index.js";
 /** Where a mail review starts: a time only; one thread is `conversations show`. */
 export declare const MAIL_REVIEW_QUERY: import("@wirecat/cli-base/query").QueryRegistry;
-/** The mail review's steps; a host lists them beside its own so its step checks know them. */
+/** The mail review's steps where a host mounted them; a host lists them beside its own so its step checks know them. */
+export declare const mailReviewSteps: (mount?: MailMount) => StepDefinition[];
+/** The steps of a mail CLI, whose profile names the mailbox. */
 export declare const MAIL_REVIEW_STEPS: ({
     id: string;
     kind: "command";