@wirecat/cli-core 0.466.0 → 0.468.0

package/dist/runs/run.js

@@ -1,10 +1,13 @@
 import { randomUUID } from "node:crypto";
-import { appendFileSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { appendFileSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { userInfo } from "node:os";
+import { join, sep } from "node:path";
 import { createRecordLog, resolvePaths, writeSecurely } from "@wirecat/cli-base";
 import { LOG_ATTRIBUTES } from "./log-attributes.js";
 import { fromLogAttributes, logAttributes, snakeLogger } from "./log-keys.js";
 export const KEEP_RUNS_FOR_DAYS = 30;
+export const KEEP_SUCCESSFUL_RUNS_FOR_DAYS = 7;
+export const RUNS_SIZE_LIMIT_MB = 200;
 /** `<state dir>/runs` — never the cache directory: a cache is deleted to fix a cache, and a run cannot be rebuilt. */
 export const runsDirFor = (app, env = process.env) => join(resolvePaths({ appName: app.appName, prefix: app.envPrefix, env }).state, "runs");
 /**
@@ -16,12 +19,11 @@ export const runsDirFor = (app, env = process.env) => join(resolvePaths({ appNam
  *   events.jsonl   one log record per event (cli-base's `LogRecord`), no ANSI ever
  * ```
  *
- * `run.json` is written **now**, with `status: "running"`, and again by `finish`. A directory
+ * `run.json` is written as the directory opens, with `status: "running"`, and again by `finish`. A directory
  * holding events and no metadata is a special case `runs list` would carry forever.
  *
  * Each write also appends the metadata to the day's `index.jsonl`, which `runs list` and `search runs`
- * read instead of every `run.json`. It is only a cache: pruned with its day, and a day without one is read
- * the slow way.
+ * read instead of every `run.json`. It is the only record of a `lazy` run that succeeded without events.
  */
 export const startRun = (options) => {
     const now = options.now ?? (() => new Date());
@@ -30,39 +32,13 @@ export const startRun = (options) => {
     const dir = join(options.runsDir, day(startedAt), id);
     // Only while something is being recorded: a tool that is not recording has no business walking
     // that directory.
-    pruneRuns(options.runsDir, { keepDays: options.keepDays ?? KEEP_RUNS_FOR_DAYS, now: startedAt });
-    mkdirSync(dir, { recursive: true, mode: 0o700 });
-    // Created here rather than by the logger, which opens with whatever the umask allows. The
-    // directory is already 0700, so this is the second lock rather than the first — but a log file
-    // that outlives its directory, or is copied out of it, should not be the one that is readable.
-    const events = join(dir, "events.jsonl");
-    writeFileSync(events, "", { flag: "a", mode: 0o600 });
-    const file = snakeLogger(createRecordLog({
-        to: events,
-        runId: id,
-        command: options.command,
-        resource: { service: options.service, version: options.cliVersion },
-        allow: LOG_ATTRIBUTES,
-        ...(options.traceId === undefined ? {} : { traceId: options.traceId }),
-        ...(options.onError === undefined ? {} : { onError: options.onError }),
-    }));
-    const operations = new Set();
-    const codes = new Set();
-    const noted = (write) => (event, message) => {
-        const { operation, errorCode, error_code, code } = event;
-        if (typeof operation === "string")
-            operations.add(operation);
-        for (const value of [errorCode, error_code, code])
-            if (typeof value === "string")
-                codes.add(value);
-        write(event, message);
-    };
-    const logger = {
-        debug: noted(file.debug),
-        info: noted(file.info),
-        warn: noted(file.warn),
-        error: noted(file.error),
-    };
+    pruneRuns(options.runsDir, {
+        keepDays: options.keepDays ?? KEEP_RUNS_FOR_DAYS,
+        keepSuccessDays: options.keepSuccessDays ?? KEEP_SUCCESSFUL_RUNS_FOR_DAYS,
+        maxBytes: options.maxBytes ?? RUNS_SIZE_LIMIT_MB * 1024 * 1024,
+        now: startedAt,
+    });
+    refuseRealStateInTests(dir);
     const metadata = {
         runId: id,
         command: options.command,
@@ -76,8 +52,46 @@ export const startRun = (options) => {
         ...(options.traceId === undefined ? {} : { traceId: options.traceId }),
         ...options.context,
     };
-    writeRunFile(dir, metadata);
+    let file;
+    const opened = () => {
+        if (file)
+            return file;
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        // Created here rather than by the logger, which opens with whatever the umask allows. The
+        // directory is already 0700, so this is the second lock rather than the first — but a log file
+        // that outlives its directory, or is copied out of it, should not be the one that is readable.
+        const events = join(dir, "events.jsonl");
+        writeFileSync(events, "", { flag: "a", mode: 0o600 });
+        file = snakeLogger(createRecordLog({
+            to: events,
+            runId: id,
+            command: options.command,
+            resource: { service: options.service, version: options.cliVersion },
+            allow: LOG_ATTRIBUTES,
+            ...(options.traceId === undefined ? {} : { traceId: options.traceId }),
+            ...(options.onError === undefined ? {} : { onError: options.onError }),
+        }));
+        writeRunFile(dir, metadata);
+        return file;
+    };
+    if (!options.lazy)
+        opened();
     let finished = false;
+    const operations = new Set();
+    const codes = new Set();
+    const noted = (level) => (event, message) => {
+        const { operation, errorCode, error_code, code } = event;
+        if (typeof operation === "string")
+            operations.add(operation);
+        for (const value of [errorCode, error_code, code])
+            if (typeof value === "string")
+                codes.add(value);
+        // A connection a long-running server keeps can log after the run that opened it ended: that is not this run.
+        if (finished)
+            return;
+        opened()[level](event, message);
+    };
+    const logger = { debug: noted("debug"), info: noted("info"), warn: noted("warn"), error: noted("error") };
     return {
         id,
         dir,
@@ -87,7 +101,7 @@ export const startRun = (options) => {
                 return;
             finished = true;
             const completedAt = now();
-            writeRunFile(dir, {
+            const final = {
                 ...metadata,
                 ...extra,
                 status,
@@ -95,10 +109,40 @@ export const startRun = (options) => {
                 durationMs: completedAt.getTime() - startedAt.getTime(),
                 operations: [...operations].sort(),
                 codes: [...codes].sort(),
-            });
+            };
+            if (file || status !== "success") {
+                opened();
+                writeRunFile(dir, final);
+                return;
+            }
+            try {
+                mkdirSync(join(dir, ".."), { recursive: true, mode: 0o700 });
+                appendIndex(join(dir, ".."), runFileOf(final));
+            }
+            catch (error) {
+                options.onError?.(error);
+            }
         },
     };
 };
+/**
+ * The test sandbox moves HOME and the XDG folders, so a run that still resolves into the owner's own data folder is a
+ * fixture that bypassed it: thousands of test runs once landed beside the owner's real ones. The passwd entry's home
+ * is read because HOME is the very thing the sandbox changed.
+ */
+export const refuseRealStateInTests = (dir, env = process.env) => {
+    if (env.VITEST === undefined)
+        return;
+    let home;
+    try {
+        home = userInfo().homedir;
+    }
+    catch {
+        return;
+    }
+    if (dir.startsWith(join(home, ".local", "share") + sep))
+        throw new Error(`a test opened a run in the real data folder: ${dir}`);
+};
 export const runtime = () => {
     const bun = process.versions.bun;
     return bun ? `bun ${bun}` : `node ${process.versions.node}`;
@@ -113,16 +157,19 @@ export const newRunId = (startedAt, command) => {
     return `${stamp}-${slug}-${randomUUID().slice(0, 6)}`;
 };
 const INDEX = "index.jsonl";
+const appendIndex = (dayDir, written) => {
+    appendFileSync(join(dayDir, INDEX), `${JSON.stringify(written)}\n`, { mode: 0o600 });
+};
 const writeRunFile = (dir, metadata) => {
     // Atomic, so a reader never sees half of one — and 0600, because it names a profile and a
     // command even though it carries nothing of what was said.
     const written = runFileOf(metadata);
     writeSecurely(join(dir, "run.json"), `${JSON.stringify(written, null, 2)}\n`, 0o600);
     try {
-        appendFileSync(join(dir, "..", INDEX), `${JSON.stringify(written)}\n`, { mode: 0o600 });
+        appendIndex(join(dir, ".."), written);
     }
     catch {
-        // The index only makes reading faster; a day without one is read run by run.
+        // A day without an index is read run by run.
     }
 };
 const matchesListFilter = (run, filter) => (filter.runId === undefined || run.runId === filter.runId) &&
@@ -151,7 +198,7 @@ export const listRuns = (runsDir, { since, atLeast = Number.POSITIVE_INFINITY, f
  * The index says what it holds; a run it does not name — written before there was an index, by an older
  * process still running, or when the append failed — is read from its own `run.json`.
  */
-const runsOfDay = (dayDir) => {
+const indexedRuns = (dayDir) => {
     const latest = new Map();
     let raw = "";
     try {
@@ -170,8 +217,12 @@ const runsOfDay = (dayDir) => {
             // A torn line from a killed process; that run's next line, or its run.json, still says it.
         }
     }
+    return latest;
+};
+const runsOfDay = (dayDir) => {
+    const latest = indexedRuns(dayDir);
     for (const entry of safeReaddir(dayDir)) {
-        if (entry === INDEX || latest.has(entry))
+        if (entry === INDEX || entry.startsWith(".") || latest.has(entry))
             continue;
         const metadata = readRun(join(dayDir, entry));
         if (metadata)
@@ -182,12 +233,19 @@ const runsOfDay = (dayDir) => {
 export const findRun = (runsDir, id) => {
     const stamped = /^(\d{4})(\d{2})(\d{2})T/.exec(id);
     const likely = stamped ? [`${stamped[1]}-${stamped[2]}-${stamped[3]}`] : [];
-    for (const date of [...likely, ...days(runsDir)]) {
+    const dates = [...new Set([...likely, ...days(runsDir)])];
+    for (const date of dates) {
         const dir = join(runsDir, date, id);
         const metadata = readRun(dir);
         if (metadata)
             return { dir, metadata };
     }
+    // A success that logged no events is a line in its day's index and nothing else.
+    for (const date of dates) {
+        const metadata = indexedRuns(join(runsDir, date)).get(id);
+        if (metadata)
+            return { dir: join(runsDir, date, id), metadata };
+    }
     return undefined;
 };
 /**
@@ -226,17 +284,23 @@ const eventOf = (line) => {
     return { time, severity, ...logAttributes(attributes) };
 };
 /**
- * Removes every day older than `keepDays`, and answers how many days went.
+ * Removes every day older than `keepDays`, then the successful runs of every day older than `keepSuccessDays`, and
+ * answers how many days went. Then, once a day, the folder is measured against `maxBytes`: successful runs go first,
+ * oldest day first, then whole days, until it fits.
  *
- * A whole day at a time, by the directory name, so nothing has to be opened to decide — and a
- * directory that is not a date is left alone rather than guessed at.
+ * A day at a time, by the directory name and the day's index, so no run has to be opened to decide — and a directory
+ * that is not a date is left alone rather than guessed at.
  */
-export const pruneRuns = (runsDir, { keepDays, now }) => {
-    const cutoff = day(new Date(now.getTime() - keepDays * 24 * 60 * 60 * 1000));
+export const pruneRuns = (runsDir, { keepDays, keepSuccessDays = keepDays, maxBytes, now, }) => {
+    const cutoff = day(new Date(now.getTime() - keepDays * DAY_MS));
+    const successCutoff = day(new Date(now.getTime() - Math.min(keepSuccessDays, keepDays) * DAY_MS));
     let removed = 0;
     for (const date of days(runsDir)) {
-        if (date >= cutoff)
+        if (date >= cutoff) {
+            if (date < successCutoff)
+                dropSuccesses(join(runsDir, date));
             continue;
+        }
         try {
             rmSync(join(runsDir, date), { recursive: true, force: true });
             removed += 1;
@@ -245,6 +309,91 @@ export const pruneRuns = (runsDir, { keepDays, now }) => {
             // A day we cannot remove is not a reason to fail the command that was only starting.
         }
     }
+    if (maxBytes !== undefined)
+        removed += fitSize(runsDir, maxBytes, now);
+    return removed;
+};
+const DAY_MS = 24 * 60 * 60 * 1000;
+const SUCCESSES_DROPPED = ".successes-dropped";
+const SIZE_CHECKED = ".size-checked";
+/** A day's successful runs, out of its index and off the disk; once per day, marked by a file beside them. */
+const dropSuccesses = (dayDir) => {
+    const marker = join(dayDir, SUCCESSES_DROPPED);
+    try {
+        statSync(marker);
+        return;
+    }
+    catch { }
+    try {
+        const kept = [];
+        for (const [id, metadata] of indexedRuns(dayDir)) {
+            if (metadata.status === "success")
+                rmSync(join(dayDir, id), { recursive: true, force: true });
+            else
+                kept.push(JSON.stringify(runFileOf(metadata)));
+        }
+        for (const entry of safeReaddir(dayDir)) {
+            if (entry === INDEX || entry.startsWith("."))
+                continue;
+            if (readRun(join(dayDir, entry))?.status === "success")
+                rmSync(join(dayDir, entry), { recursive: true, force: true });
+        }
+        writeSecurely(join(dayDir, INDEX), kept.map((line) => `${line}\n`).join(""), 0o600);
+        writeFileSync(marker, "", { mode: 0o600 });
+    }
+    catch {
+        // Tried again at the next run's start.
+    }
+};
+const sizeOf = (path) => {
+    let total = 0;
+    for (const entry of safeReaddir(path)) {
+        const full = join(path, entry);
+        try {
+            const stat = statSync(full);
+            total += stat.isDirectory() ? sizeOf(full) : stat.size;
+        }
+        catch { }
+    }
+    return total;
+};
+/** Measuring walks every file, so it runs at most once a day; a burst can overshoot until the next day's check. */
+const fitSize = (runsDir, maxBytes, now) => {
+    const stamp = join(runsDir, SIZE_CHECKED);
+    const today = day(now);
+    try {
+        if (readFileSync(stamp, "utf8").trim() === today)
+            return 0;
+    }
+    catch { }
+    const dates = days(runsDir).sort();
+    const sizes = new Map(dates.map((date) => [date, sizeOf(join(runsDir, date))]));
+    let total = [...sizes.values()].reduce((sum, size) => sum + size, 0);
+    let removed = 0;
+    // Today is left to the age rule: a day marked done would keep the successes it gains later.
+    for (const date of dates) {
+        if (total <= maxBytes || date === today)
+            break;
+        dropSuccesses(join(runsDir, date));
+        const after = sizeOf(join(runsDir, date));
+        total -= (sizes.get(date) ?? 0) - after;
+        sizes.set(date, after);
+    }
+    for (const date of dates) {
+        if (total <= maxBytes || date === today)
+            break;
+        try {
+            rmSync(join(runsDir, date), { recursive: true, force: true });
+            total -= sizes.get(date) ?? 0;
+            removed += 1;
+        }
+        catch { }
+    }
+    try {
+        mkdirSync(runsDir, { recursive: true, mode: 0o700 });
+        writeFileSync(stamp, today, { mode: 0o600 });
+    }
+    catch { }
     return removed;
 };
 const day = (date) => date.toISOString().slice(0, 10);

package/dist/runs/scope.d.ts

@@ -1,3 +1,4 @@
+import type { EventSink } from "./events.js";
 export interface RunScope {
     runId: string;
     command: string;
@@ -7,6 +8,8 @@ export interface RunScope {
     traceId?: string;
     /** The profile the run is for, so a hint deep in a service can name the command with it. */
     profile?: string;
+    /** The run's event sink, for a transport far below the command (a wire middleware) that is not handed one. */
+    events?: EventSink;
 }
 /**
  * The run a log line written now belongs to, for a writer that is not handed one — the send journal,
@@ -14,6 +17,8 @@ export interface RunScope {
  */
 export declare const currentRun: () => RunScope;
 export declare const inRun: <T>(scope: RunScope, body: () => T) => T;
+/** One event into the run under way, or nowhere: outside a run, or in a run that keeps nothing. */
+export declare const runEvent: EventSink;
 /**
  * A command as a person types it: `max personal store migrate`. A hint without the profile fails when copied,
  * since no profile is assumed; outside a run with a profile it stays `max store migrate`.
@@ -41,3 +46,10 @@ export declare const childTrace: () => {
     traceId: string;
     traceparent: string;
 };
+export interface Attempt {
+    attempt: number;
+    waitMs?: number;
+}
+/** Marks the calls made under it as one try of a retried call: a wire event without its own attempt takes this one. */
+export declare const withAttempt: <T>(attempt: Attempt, work: () => T) => T;
+export declare const currentAttempt: () => Attempt | undefined;

package/dist/runs/scope.js

@@ -21,6 +21,8 @@ export const currentRun = () => {
     return processScope;
 };
 export const inRun = (scope, body) => scopes.run(scope, body);
+/** One event into the run under way, or nowhere: outside a run, or in a run that keeps nothing. */
+export const runEvent = (event) => scopes.getStore()?.events?.(event);
 /**
  * A command as a person types it: `max personal store migrate`. A hint without the profile fails when copied,
  * since no profile is assumed; outside a run with a profile it stays `max store migrate`.
@@ -52,3 +54,7 @@ export const childTrace = () => {
     const traceId = hex(16);
     return { traceId, traceparent: `00-${traceId}-${hex(8)}-01` };
 };
+const attempts = new AsyncLocalStorage();
+/** Marks the calls made under it as one try of a retried call: a wire event without its own attempt takes this one. */
+export const withAttempt = (attempt, work) => attempts.run(attempt, work);
+export const currentAttempt = () => attempts.getStore();

package/dist/services/embeddings-maintenance.js

@@ -19,10 +19,8 @@ const PER_SESSION = 8;
 const PER_REQUEST = 256;
 /** e5's tokenizer reads ~3.7 characters a token in Russian; 3 keeps the bound above the real count. */
 const CHARS_PER_TOKEN_AT_LEAST = 3;
-const notDownloaded = (deps, id) => new CliError("not_found", `${id} is not downloaded — \`${typedCommand(deps.messenger.app.command, `models download ${id}`)}\``, {
-    reason: "model.not-downloaded",
-    model: id,
-});
+/** The download is the error's `next` step, named only by a CLI that has `models` (`failureSteps`). */
+const notDownloaded = (id) => new CliError("not_found", `${id} is not downloaded on this machine`, { reason: "model.not-downloaded", model: id });
 export const notBuiltError = (deps, chatId) => new CliError("not_found", `chat ${chatId} has no conversations yet — \`${typedCommand(deps.messenger.app.command, `conversations links rebuild --chat ${chatId}`)}\``);
 export const embeddingTarget = (deps, choice = DEFAULT_TEXT_MODEL) => {
     if (typeof choice !== "string") {
@@ -50,7 +48,7 @@ export const embeddingTarget = (deps, choice = DEFAULT_TEXT_MODEL) => {
         perBatch: PER_SESSION,
         open: async ({ threads, apart = false, } = {}) => {
             if (!isTextModelInstalled(model, directory))
-                throw notDownloaded(deps, model.id);
+                throw notDownloaded(model.id);
             if (apart) {
                 const { openProcess } = await import("../embeddings/process.js");
                 return openProcess(model, directory, { threads: threads ?? defaultThreads() });
@@ -264,7 +262,7 @@ export const embeddingsMaintenance = (deps) => {
             const account = await deps.account();
             const target = embeddingTarget(deps, choice);
             if (embed && !build && !target.installed)
-                throw notDownloaded(deps, target.id);
+                throw notDownloaded(target.id);
             const chatId = chat === undefined ? undefined : await storedChatId(deps.messenger, chat, store, account, { includeLeft: true });
             const scan = async () => ({
                 chats: (await readinessOf(deps, chatId, target.key)).sort(byOldestBuild),

package/dist/services/patience.js

@@ -1,13 +1,16 @@
 import { setTimeout as sleep } from "node:timers/promises";
 import { isCliFailure } from "../errors/failures.js";
+import { withAttempt } from "../runs/scope.js";
 /** Waits longer than this are not sat out: the run stops, and the next one resumes. */
 const LONGEST_WAIT_MS = 5 * 60 * 1000;
 /** Sits out a provider's "wait N seconds" when it is short, a few times; a long one ends the run. */
 export const patiently = async (request, note, stop) => {
+    let waited;
     for (let attempt = 1;; attempt += 1) {
         stop.throwIfAborted();
         try {
-            return await request();
+            // A transport below logs this call as the retry it is, with the wait before it.
+            return await withAttempt({ attempt, ...(waited === undefined ? {} : { waitMs: waited }) }, request);
         }
         catch (error) {
             const wait = isCliFailure(error) && error.code === "rate_limited" ? Number(error.details?.retry_after_ms) : NaN;
@@ -15,6 +18,7 @@ export const patiently = async (request, note, stop) => {
                 throw error;
             note(`asked to wait ${Math.ceil(wait / 1000)} s — waiting, then going on`);
             await sleep(wait, undefined, { signal: stop }).catch(() => { });
+            waited = wait;
             if (stop.aborted)
                 throw error;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-core",
-  "version": "0.466.0",
+  "version": "0.468.0",
   "description": "The messenger-neutral half of a messaging CLI: domain model, message locators, rendering, name resolution, the SQLite seam, the command skeleton and shared read commands, the send guard, run records and the message store",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",