@wirecat/cli-core 0.562.0 → 0.563.0

package/CHANGELOG.md

@@ -5,6 +5,68 @@ Notable changes to `@wirecat/cli-core` (`@wirecat/cli-messaging` up to 0.261.0,
 minor version may break callers, and says how under "Changed — may break callers". `pnpm docs:check` checks the
 shape of this file.
 
+## Unreleased
+
+## 0.563.0 — 03.11.2026
+
+### Changed — may break callers
+
+- **Mail sync reads attachments up to 10 MB a file by default, and can skip them.** Until now every attachment was
+  read, whatever its size; at the next bump a file over 10 MB is no longer read into the index unless the caller
+  passes a policy. `MailSyncOptions.attachments` takes a `MailAttachmentPolicy` (`read`, `maxBytes`); left out it is
+  `DEFAULT_ATTACHMENT_POLICY`. A file the policy leaves is stored with its name, type and size but no text, with
+  `extractionError` `not-read` or `too-large` (`POLICY_SKIPS`), and the run's `attachments` log says the same.
+  Partial completion and `retryAttachments` follow it too.
+- **Moving a task to another project moves its subtasks with it.** `tasks.edit(id, { project })` on a task with
+  subtasks no longer refuses with `task.has-subtasks`; that reason is gone. Every subtask, all the way down, takes the
+  next key in the new project and keeps its parent, and its old key still finds it. The answer names them as
+  `movedSubtasks: [{ from, to }]`, old key and new; the field is left out when nothing moved with the task. A subtask
+  moved on its own still needs `parent: null` in the same edit (`task.is-subtask`).
+
+- **Owner-only proposals refuse an agent on every decide path.** `mayDecide` and `assertMayDecide` now read
+  the row's stored `kind`: a `mail_findings` or `meeting_findings` row is the owner's alone, whatever
+  `agent_decisions` says. The registry's `get` and `list` rows carry `ownerOnly` from their kind, and the generic
+  action kind marks a stored findings row too, so a host checking `assertMayDecide(await registry.get(id), …)` is
+  refused. `approveAsTask` and `proposedActions.approve` / `reject` refuse a mail findings batch as they refuse
+  meeting and evidence findings (`mail-findings.dedicated-review`), and the generic action kind no longer lists any
+  findings batch. Meeting findings were open to another agent with a reason before; now only the owner reviews them.
+
+### Added
+
+- **An answer over the output cap says what to run instead (WC-OUT-22).** The `output.too-large` failure now names up
+  to two reads, both safe to run unasked: the same command line with `--compact`, when the command declares a row and
+  was not compact already, and the same line with a `--limit` scaled down to fit. The lines are rebuilt from the
+  words the caller typed, never from the answer. The failure also carries `needed_bytes`.
+- **A JSON answer over 256 KiB adds one step to the compact form.** The answer is still printed whole. Nothing is
+  added when the answer already names two steps, over MCP, or for a command with no declared row.
+- **`search messages --chat` and `search all --chat` say how to search one chat:** `chat:<chat>` in the query.
+
+- **`readEmailWhole` reads one stored email again from its mail server, every attachment of it with no limit.** It
+  saves the new text on the email as a sync does, keeping its mailboxes, flags and rule, and answers each attachment's
+  bytes for the caller to save. Gmail's email is found by id, another server's at its stored place.
+  `store.mail.emailPlace(accountId, externalId)` gives an email's thread and stored places.
+- **`stats messages responses`**: how fast replies come in one-to-one chats, the owner's (`--who me`) or the other
+  side's (`--who others`): count, median, p90, mean and four time buckets, in total or `--by day` in `--timezone`.
+  Several messages in a row followed by one answer are one reply, timed from the first. Reads by index, so all time
+  works on a large store; the query after `--` takes `date:`, `chat:` and `kind:` only.
+- **`stats messages waiting`**: how many chats wait on the owner — a one-to-one chat whose newest message is a
+  question, or a group whose newest message mentions or replies to the owner — with the messages since the owner
+  last wrote, the oldest of them, and the split by kind. Muted or archived one-to-one chats are left out, as in
+  `inbox`.
+- **tg, max, wa, mail, gcal and drive's config file holds every shared setting with its default.** A first run now
+  writes all of them into `defaults`, not five; `config set` and `config unset` add the missing ones (but not the one
+  just unset); and the new `<cli> config migrate` fills an existing file. Your values, their order and unknown keys
+  stay; a file without `defaults` gets that section, and no other section is created. `config show` gives each of
+  these settings its `default` and `description`, and no longer creates the file when there is none. `settingsFor`
+  returns `declaredSettings` and `migrate(path)`; `extension.settings` declares a CLI's own (cli-base WC-CMD-30).
+  Settings with no single default (`timeout_ms`, `color`, `requests_per_minute`, the embedding model) and objects
+  (`permissions`, `models`) are left out.
+- **`MailReads.mount`: the steps a mail review hands on name where the host mounted it.** A host that mounts `review`
+  and `messages acknowledge` elsewhere passes their paths and the option naming the mailbox — memo passes
+  `review: "mail review"`, `conversation: null` (it mounts no thread read) and `mailbox: { option: "source", value }`
+  — and `next` names those paths and `--source email:<account>`. `mailReviewSteps(mount)` gives the definitions for
+  a host's step checks; a mail CLI leaves it out, and its step lines carry the profile as before.
+
 ## 0.562.0 — 03.11.2026
 
 ### Added

package/dist/cli/config-command.js

@@ -30,6 +30,7 @@ export const configCommand = (app, config, { permissionKey = config.permissions,
         const bot = this.opts().bot === true;
         const context = baseContext(this, (flags, options) => config.resolveSettings(flags, {
             ...options,
+            readOnly: true,
             needsProfile: false,
             withIssues: true,
             ...(bot ? { kind: "bot" } : {}),
@@ -48,7 +49,13 @@ export const configCommand = (app, config, { permissionKey = config.permissions,
             paths_overridden: overridden,
             settings: [...config.allSettings, "command_timeout_ms"]
                 .filter((setting) => bot || setting !== "read_other_bots")
-                .map((setting) => sourced(settings, setting)),
+                .map((setting) => {
+                const declared = config.declaredSettings.find(({ key }) => key === `defaults.${setting}`);
+                return {
+                    ...sourced(settings, setting),
+                    ...(declared ? { default: declared.default, description: declared.description } : {}),
+                };
+            }),
             store_settings: await storeSettings(env),
         }));
         for (const issue of [
@@ -144,9 +151,19 @@ export const configCommand = (app, config, { permissionKey = config.permissions,
             }));
         });
     }
+    command.addCommand(migrateCommand(app, config));
     command.addCommand(repairCommand(app, config));
     return command;
 };
+const migrateCommand = (app, config) => profileFree(grantsAuthority(annotate(new Command("migrate"), { effects: LOCAL_WRITE, examples: [`${app.command} config migrate`] })))
+    .description("write each setting the file lacks at its default, keeping yours")
+    .action(function () {
+    const context = baseContext(this, (flags, options) => config.resolveSettings(flags, { ...options, needsProfile: false, withIssues: true }));
+    const file = context.settings.configPath;
+    const added = config.migrate(file);
+    renderAnswer(this, context, itemOf({ config_file: file, added }));
+    context.renderer.note(added.length > 0 ? `added ${added.join(", ")} to ${file}` : `${file} already has every setting`);
+});
 /**
  * Mends JSON syntax with one reading and keeps every value (NEED-2178): no network, no AI, since the file may hold
  * keys. Anything else is refused with nothing changed.

package/dist/cli/envelope.js

@@ -5,6 +5,7 @@ import * as v from "valibot";
 import { currentRun } from "../runs/scope.js";
 import { compactText, entityRows, rowShapeOf, rowsOfEntity, TEXT_CHARS } from "./compact.js";
 import { environmentOf, setExitCode } from "./context.js";
+import { largeAnswerSteps, SOFT_OUTPUT_BYTES } from "./output-budget.js";
 import { withoutProviderRefs } from "./provider-refs.js";
 import { nextStep, rootOf, runnable, stepLine, withLines, withSafety } from "./steps.js";
 /** Every answer: a list or one thing, with items of `item` — any value where the command declares no entity. */
@@ -131,6 +132,16 @@ export const sealed = (value) => {
 };
 /** The steps a compact answer prints, each rerunning in the compact form the caller chose. */
 const compactSteps = (root, steps) => steps.map((step) => step.kind === "command" ? { ...step, line: `${step.line ?? stepLine(root, step)} ${COMPACT_FLAG}` } : step);
+/** A JSON answer past the soft budget, printed whole, with one more step: the same read in the compact form. */
+const withLargeAnswerStep = (command, body) => {
+    if ((body.next?.length ?? 0) >= MAX_NEXT_STEPS)
+        return body;
+    const added = largeAnswerSteps(command);
+    if (added.length === 0 || Buffer.byteLength(JSON.stringify(body)) <= SOFT_OUTPUT_BYTES)
+        return body;
+    const root = rootOf(command);
+    return { ...body, next: [...(body.next ?? []), ...withLines(root, runnable(root, added))] };
+};
 /** An answer as JSON lines: one line per item, then the end line. One thing is a list of one that has no more. */
 const linesOf = (body) => jsonlOf("items" in body ? body : { items: [body.item], page: { mode: "page", limit: 1, has_more: false }, meta: body.meta });
 /** An answer as JSON-lines records, for a writer that streams objects: one per item, then the end record. */
@@ -151,9 +162,10 @@ export const renderAnswer = (command, { renderer, format, streams, compact, full
     const kept = withoutProviderRefs({ ...body, ...(next.length > 0 ? { next } : {}) });
     if (next.length === 0)
         delete kept.next;
-    const whole = sealed(kept);
+    const sealedBody = sealed(kept);
     const environment = environmentOf(command);
     const drawn = compact && !environment.agent;
+    const whole = format === "json" && !drawn && !environment.agent ? withLargeAnswerStep(command, sealedBody) : sealedBody;
     if (drawn) {
         const lined = whole.next ? { ...whole, next: compactSteps(root, whole.next) } : whole;
         const timezone = Intl.DateTimeFormat().resolvedOptions().timeZone;

package/dist/cli/execution.js

@@ -116,6 +116,7 @@ export const execution = (streams, { timeoutMs, fields, maxOutputBytes = DEFAULT
                         reason: "output.too-large",
                         max_bytes: maxOutputBytes,
                         emitted_bytes: bytes,
+                        needed_bytes: bytes + size,
                         partial_output: bytes > 0,
                     });
                 bytes += size;

package/dist/cli/messenger/reply-stats-command.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+import { type Messenger } from "./context.js";
+export declare const replyResponsesCommand: (messenger: Messenger) => Command;
+export declare const replyWaitingCommand: (messenger: Messenger) => Command;

package/dist/cli/messenger/reply-stats-command.js

@@ -0,0 +1,57 @@
+import { annotate } from "@wirecat/cli-base/commands";
+import { Command, Option } from "commander";
+import { LOCAL_READ } from "../effects.js";
+import { renderAnswer } from "../envelope.js";
+import { messengerContext } from "./context.js";
+import { refuseJsonl, responsesAnswer, waitingAnswer } from "./stats-answers.js";
+const QUERY = "date:, chat: and kind: terms, AND-ed — date>=30d, date:[60d TO 30d]; none reads all time";
+const GUIDE = "Guide: https://github.com/WireCatLabs/cli-core/blob/main/docs/rankings.md#reply-times-and-chats-waiting-on-you";
+const minutes = (ms) => (ms === null ? "—" : `${Math.round(ms / 60_000)} min`);
+export const replyResponsesCommand = (messenger) => annotate(new Command("responses"), { effects: LOCAL_READ, output: { entity: "response_times" } })
+    .summary("how fast replies come in one-to-one chats: median, p90, mean and buckets")
+    .description("how long the owner took to answer (--who me), or the other side took to answer the owner (--who others), in " +
+    "one-to-one chats — the local store only. Several messages in a row followed by one answer count as one " +
+    "reply, timed from the first unanswered message; the day of a row is the day of the reply")
+    .argument("[query...]", QUERY)
+    .addOption(new Option("--who <side>", "whose replies: the owner's or the other side's").choices(["me", "others"]))
+    .addOption(new Option("--by <group>", "one row per calendar day of the reply, or none").choices(["day", "total"]))
+    .option("--timezone <zone>", "the IANA timezone for calendar days and date: bounds")
+    .option("--source <accounts>", "every account of this messenger held in the store; personal, bots or all")
+    .addHelpText("after", GUIDE)
+    .action(async function (words) {
+    const context = messengerContext(this, messenger);
+    refuseJsonl(context.format);
+    const { who, by, timezone, source } = this.opts();
+    const found = await context.withServices((services) => services.replyStats.responses({
+        who: who ?? "me",
+        by: by ?? "total",
+        ...(words.length ? { text: words.join(" ") } : {}),
+        ...(timezone === undefined ? {} : { timezone }),
+        ...(source === undefined ? {} : { source }),
+    }));
+    renderAnswer(this, context, responsesAnswer(found), () => [
+        `${found.replies} replies · median ${minutes(found.medianMs)} · p90 ${minutes(found.p90Ms)} · mean ${minutes(found.meanMs)}`,
+        ...found.rows.map((row) => `${row.key}  ${row.replies} replies · median ${minutes(row.medianMs)}`),
+        "",
+    ].join("\n"));
+});
+export const replyWaitingCommand = (messenger) => annotate(new Command("waiting"), { effects: LOCAL_READ, output: { entity: "waiting_chats" } })
+    .summary("chats whose newest message asks the owner something")
+    .description("how many chats wait on the owner — the local store only: a one-to-one chat whose newest message is a " +
+    "question, or a group whose newest message mentions the owner or replies to them. Muted or archived " +
+    "one-to-one chats are left out, as inbox leaves them out; date: bounds the newest message's time")
+    .argument("[query...]", QUERY)
+    .option("--timezone <zone>", "the IANA timezone for date: bounds")
+    .option("--source <accounts>", "every account of this messenger held in the store; personal, bots or all")
+    .addHelpText("after", GUIDE)
+    .action(async function (words) {
+    const context = messengerContext(this, messenger);
+    refuseJsonl(context.format);
+    const { timezone, source } = this.opts();
+    const found = await context.withServices((services) => services.replyStats.waiting({
+        ...(words.length ? { text: words.join(" ") } : {}),
+        ...(timezone === undefined ? {} : { timezone }),
+        ...(source === undefined ? {} : { source }),
+    }));
+    renderAnswer(this, context, waitingAnswer(found), () => `${found.chats} chats wait on you (${found.byKind.private} one-to-one, ${found.byKind.group} groups) · ${found.messages} messages${found.oldestAt ? ` · oldest ${found.oldestAt}` : ""}\n`);
+});

package/dist/cli/messenger/search-command.js

@@ -5,6 +5,7 @@ import { SAVE_HELP } from "../../meetings/index.js";
 import { searchNotesOf } from "../../services/notes-search.js";
 import { LOCAL_READ, REMOTE_READ } from "../effects.js";
 import { renderAnswer } from "../envelope.js";
+import { withOptionHints } from "../option-hints.js";
 import { positiveCount } from "../paging.js";
 import { runsSearchCommand } from "../runs/search-command.js";
 import { commandAt } from "../steps.js";
@@ -193,5 +194,12 @@ export const searchCommand = (messenger, { topics = false } = {}) => {
         if (command)
             annotate(command, { examples: [`${messenger.app.command} personal search ${path} ${args}`] });
     }
+    for (const path of ["all", "messages"]) {
+        const command = commandAt(search, path);
+        if (command)
+            withOptionHints(command, {
+                "--chat": `search in one chat with chat:<chat> in the query: search ${path} 'chat:<chat> words'`,
+            });
+    }
     return search;
 };

package/dist/cli/messenger/stats-answers.d.ts

@@ -8,6 +8,7 @@ import type { AdminEvidenceFound, AdminFound } from "../../services/admin-statis
 import type { ChatStats } from "../../services/chat-stats.js";
 import type { MessageStats } from "../../services/messages-search.js";
 import type { RankingFound } from "../../services/rankings.js";
+import type { ReplyTimes, Waiting } from "../../services/reply-stats.js";
 import type { RetentionService } from "../../services/retention.js";
 import type { AccountKey, RankedEvidence } from "../../store/store.js";
 import type { GroupStats } from "../../tasks/index.js";
@@ -72,4 +73,6 @@ export declare const chatStatsAnswer: (stats: ChatStats, account: AccountKey, me
 export declare const MEMBERS_UNRECORDED = "joins and leaves are not recorded for this chat yet, so they are not counted";
 /** `stats tasks show`, CLI and MCP alike. */
 export declare const taskStatsAnswer: (rows: GroupStats[], account: AccountKey) => ItemBody<Of<"task_stats">>;
+export declare const responsesAnswer: (found: ReplyTimes) => ItemBody<Of<"response_times">>;
+export declare const waitingAnswer: (found: Waiting) => ItemBody<Of<"waiting_chats">>;
 export {};

package/dist/cli/messenger/stats-answers.js

@@ -420,3 +420,21 @@ export const taskStatsAnswer = (rows, account) => itemOf({
         median_close_ms: row.medianCloseMs ?? null,
     })),
 });
+const replyFigures = (one) => ({
+    replies: one.replies,
+    median_ms: one.medianMs,
+    p90_ms: one.p90Ms,
+    mean_ms: one.meanMs,
+});
+export const responsesAnswer = (found) => itemOf({
+    who: found.who,
+    ...replyFigures(found),
+    buckets: {
+        under_5m: found.buckets.under5m,
+        under_1h: found.buckets.under1h,
+        under_1d: found.buckets.under1d,
+        over_1d: found.buckets.over1d,
+    },
+    rows: found.rows.map((row) => ({ key: row.key, ...replyFigures(row) })),
+});
+export const waitingAnswer = (found) => itemOf({ chats: found.chats, messages: found.messages, oldest_at: found.oldestAt, by_kind: found.byKind });

package/dist/cli/messenger/stats-command.js

@@ -20,6 +20,7 @@ import { countersCommand } from "./counters-command.js";
 import { messagesStatsCommand } from "./messages-stats-command.js";
 import { officialStatsCommand } from "./official-stats-command.js";
 import { rankingEvidenceCommand, rankingsTopCommand } from "./rankings-command.js";
+import { replyResponsesCommand, replyWaitingCommand } from "./reply-stats-command.js";
 import { retentionCommand } from "./retention-command.js";
 import { chartAnswer, refuseJsonl } from "./stats-answers.js";
 import { tasksStatsCommand } from "./tasks-command.js";
@@ -31,6 +32,8 @@ export const statsCommand = (messenger, loadRenderer = chartRenderer) => {
         .addCommand(countersCommand(messenger))
         .addCommand(adminStatisticsCommand(messenger, "unanswered"))
         .addCommand(adminStatisticsCommand(messenger, "discussion"))
+        .addCommand(replyResponsesCommand(messenger))
+        .addCommand(replyWaitingCommand(messenger))
         .addCommand(rankingsTopCommand(messenger, "messages"))
         .addCommand(rankingEvidenceCommand(messenger, "messages")));
     stats.addCommand(new Command("contacts")
@@ -96,10 +99,12 @@ export const statsCommand = (messenger, loadRenderer = chartRenderer) => {
         "messages counters sync": '--chat "Book club" --dry-run',
         "messages counters show": '--chat "Book club" --limit 10',
         "messages discussion": 'chat:"Book club"',
+        "messages responses": "--who me --by day --timezone Europe/Madrid -- date>=30d",
         "messages evidence": '"$message" --selection "$selection" --component reactions',
         "messages show": '--chat "Book club" --by day',
         "messages top": 'chat:"Book club" --limit 10',
         "messages unanswered": 'chat:"Project room"',
+        "messages waiting": "kind:private",
         "tasks show": '--chat "Project room"',
     };
     for (const [path, args] of Object.entries(examples)) {

package/dist/cli/output-budget.d.ts

@@ -0,0 +1,26 @@
+import type { NextStep } from "@wirecat/cli-base/standards";
+import type { Command } from "commander";
+/** About a third of a 200k-token context at ~3 bytes per token (inferred, not measured). */
+export declare const SOFT_OUTPUT_BYTES: number;
+/** The same read in a form that fits the cap: one line per item, then a `--limit` scaled down to fit (WC-OUT-22). */
+export declare const tooLargeSteps: (command: Command, { maxBytes, neededBytes }: {
+    maxBytes: number;
+    neededBytes: number;
+}) => ({
+    kind: "command";
+    step: string;
+    command: string;
+    args: {
+        [x: string]: unknown;
+    };
+    line?: string | undefined;
+    why: string;
+    safe_to_auto_execute: boolean;
+} | {
+    kind: "user_action";
+    step: string;
+    why: string;
+    safe_to_auto_execute: false;
+})[];
+/** The step a large JSON answer adds: the same read, one line per item. */
+export declare const largeAnswerSteps: (command: Command) => NextStep[];

package/dist/cli/output-budget.js

@@ -0,0 +1,73 @@
+import { entityRows, GENERIC_ROW, rowShapeOf } from "./compact.js";
+import { environmentOf } from "./context.js";
+import { rootOf } from "./steps.js";
+/** About a third of a 200k-token context at ~3 bytes per token (inferred, not measured). */
+export const SOFT_OUTPUT_BYTES = 256 * 1024;
+const CARRIED = ["json", "compact", "offline", "timeout", "full", "brief", "maxOutputBytes"];
+const NOT_WITH_COMPACT = new Set(["json", "brief"]);
+const snake = (name) => name.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+const typed = (command, key) => command.getOptionValueSource(key) === "cli";
+/**
+ * The words the caller typed, as step arguments: never a default, never text an answer carried (WC-OUT-9). A
+ * `--no-x` flag and `--json=<fields>` have no form a step can carry, so a line holding one gets no step.
+ */
+const typedArgs = (command) => {
+    const root = rootOf(command);
+    if (root.getOptionValue("fields") !== undefined)
+        return undefined;
+    if (command.options.some((option) => option.negate && typed(command, option.attributeName())))
+        return undefined;
+    const positional = command.registeredArguments.flatMap((argument, index) => {
+        const value = command.processedArgs[index];
+        const word = Array.isArray(value) ? value.join(" ") : value;
+        return word === undefined || word === "" ? [] : [[argument.name(), word]];
+    });
+    const own = command.options
+        .map((option) => option.attributeName())
+        .filter((key) => typed(command, key))
+        .map((key) => [snake(key), command.getOptionValue(key)]);
+    const global = CARRIED.filter((key) => typed(root, key)).map((key) => [snake(key), root.getOptionValue(key)]);
+    return Object.fromEntries([...positional, ...own, ...global]);
+};
+const declaresRow = (command) => {
+    const { rows } = environmentOf(command);
+    return rowShapeOf(command, rows && entityRows(rows)) !== GENERIC_ROW;
+};
+const pathOf = (command) => {
+    const words = [];
+    for (let at = command; at.parent; at = at.parent)
+        words.unshift(at.name());
+    return words.join(" ");
+};
+const step = (command, id, args, why) => ({
+    kind: "command",
+    step: id,
+    command: pathOf(command),
+    args,
+    why,
+    safe_to_auto_execute: true,
+});
+const compactStep = (command, args, why) => rootOf(command).getOptionValue("compact") === true || !declaresRow(command)
+    ? []
+    : [
+        step(command, "output.compact", { ...Object.fromEntries(Object.entries(args).filter(([key]) => !NOT_WITH_COMPACT.has(key))), compact: true }, why),
+    ];
+/** The same read in a form that fits the cap: one line per item, then a `--limit` scaled down to fit (WC-OUT-22). */
+export const tooLargeSteps = (command, { maxBytes, neededBytes }) => {
+    const args = typedArgs(command);
+    if (!args)
+        return [];
+    const limit = Number(command.getOptionValue("limit"));
+    const fits = Math.floor(((limit * maxBytes) / neededBytes) * 0.9);
+    return [
+        ...compactStep(command, args, "the answer is over the output cap as JSON; one line per item keeps every ref"),
+        ...(Number.isSafeInteger(limit) && fits >= 1 && fits < limit
+            ? [step(command, "output.limit", { ...args, limit: fits }, `about ${fits} items fit under the output cap`)]
+            : []),
+    ];
+};
+/** The step a large JSON answer adds: the same read, one line per item. */
+export const largeAnswerSteps = (command) => {
+    const args = typedArgs(command);
+    return args ? compactStep(command, args, "the answer is large as JSON; one line per item keeps every ref") : [];
+};

package/dist/cli/program.js

@@ -29,6 +29,7 @@ import { installHelp } from "./help/first-screen.js";
 import { showInputFields } from "./input-fields.js";
 import { MAX_BUFFERED_INPUT, provideInputPolicy } from "./input-policy.js";
 import { checkJson, liftJson } from "./json-fields.js";
+import { tooLargeSteps } from "./output-budget.js";
 import { PreviewComplete, preview } from "./preview.js";
 import { commandWords, isProfileName, liftProfile, sampleCommand, takesProfile, valuedOptions } from "./profile.js";
 import { absolutePaths, relayTarget } from "./relay-route.js";
@@ -705,6 +706,15 @@ const commandPath = (program, rest) => {
     }
     return words.join(" ");
 };
+const budgetSteps = (program, path, failure) => {
+    const command = path ? commandAt(program, path) : undefined;
+    if (!command || !(failure instanceof CliError) || failure.details?.reason !== "output.too-large")
+        return [];
+    const { max_bytes: maxBytes, needed_bytes: neededBytes } = failure.details;
+    return typeof maxBytes === "number" && typeof neededBytes === "number"
+        ? tooLargeSteps(command, { maxBytes, neededBytes })
+        : [];
+};
 const failed = ({ app }, program, rest, error, settled, debug) => {
     const path = commandPath(program, program.args.length > 0 ? program.args : rest);
     const told = error instanceof NoProfileHere && !commandAt(program, "setup") ? error.withoutSetup(path) : error;
@@ -718,7 +728,10 @@ const failed = ({ app }, program, rest, error, settled, debug) => {
         ...(effects ? { effects } : {}),
     });
     const { next: _named, ...said } = built.error;
-    const steps = failureSteps(program, built.error);
+    const steps = failureSteps(program, {
+        ...built.error,
+        next: [...(built.error.next ?? []), ...budgetSteps(program, path, failure)],
+    });
     const object = { ...built, error: { ...said, ...(steps.length > 0 ? { next: steps } : {}) } };
     showInputFields(object, (path && commandAt(program, path)) || program);
     const command = path || app.command;

package/dist/cli/settings.d.ts

@@ -7,6 +7,7 @@ import { type Level, type PermissionKey } from "../sends/permissions.js";
 import { type HistoryLimits } from "../services/history-limits.js";
 import { type ConfigIssue } from "./config-issues.js";
 import type { CommandPermissions } from "./permission-keys.js";
+import { type DeclaredSetting } from "./setting-defaults.js";
 export declare const plain: (rule: string) => (issue: v.BaseIssue<unknown>) => string;
 export declare const count: v.SchemaWithPipe<readonly [v.NumberSchema<(issue: v.BaseIssue<unknown>) => string>, v.IntegerAction<number, (issue: v.BaseIssue<unknown>) => string>, v.MinValueAction<number, 1, (issue: v.BaseIssue<unknown>) => string>]>;
 export declare const flag: v.BooleanSchema<(issue: v.BaseIssue<unknown>) => string>;
@@ -32,6 +33,8 @@ export interface SettingsExtension<T extends object = Record<never, never>> {
     profile?: v.ObjectEntries;
     /** For the whole program only, never per profile. */
     defaults?: v.ObjectEntries;
+    /** Its own scalar settings, written into the file's `defaults` beside the shared ones (WC-CMD-30). */
+    settings?: readonly DeclaredSetting[];
     /** Profiles this messenger keeps in files of its own, beyond the config file and the remembered accounts. */
     profiles?: (env: NodeJS.ProcessEnv) => string[];
     /**
@@ -229,6 +232,8 @@ export declare const settingsFor: <T extends object = Record<never, never>>(app:
         kind?: ProfileKind | undefined;
         root?: boolean;
     }) => unknown;
+    migrate: (path: string) => string[];
+    declaredSettings: DeclaredSetting[];
     allSettings: string[];
     defaultsOnlyKeys: string[];
     schema: v.StrictObjectSchema<{

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,