@wirecat/cli-core 0.466.0 → 0.468.0

package/dist/runs/log-attributes.js

@@ -16,6 +16,10 @@ const diagnostic = {
     outcome: true,
     errorCode: true,
     providerError: true,
+    level: true,
+    transport: true,
+    attempt: true,
+    waitMs: true,
     code: true,
     detail: true,
     reason: true,
@@ -63,12 +67,14 @@ const background = [
 ];
 /** A crash: where it happened, never what it said. */
 const crash = ["errorClass", "frames"];
+/** What a capped run did not write: how many, by operation. */
+const dropped = ["dropped"];
 /**
  * Every attribute key cli-core's writers log, as written: snake_case (`logAttributes`). `createRecordLog`
  * blanks any other, cli-base's own camelCase list included.
  */
 export const LOG_ATTRIBUTES = [
-    ...new Set([...Object.keys(diagnostic), ...Object.keys(send), ...background, ...crash].map((key) => Object.keys(logAttributes({ [key]: true }))[0])),
+    ...new Set([...Object.keys(diagnostic), ...Object.keys(send), ...background, ...crash, ...dropped].map((key) => Object.keys(logAttributes({ [key]: true }))[0])),
 ].sort();
 /** For `cli-dev lint --schemas`, under the name `log_attributes`. */
 export const logAttributesSchema = () => logAttributesJsonSchema(LOG_ATTRIBUTES);

package/dist/runs/log-events.js

@@ -10,6 +10,11 @@ export const CORE_LOG_EVENTS = defineLogEvents([
         keys: ["operation", "reason"],
     },
     { id: "command.crashed", meaning: "a command failed on a bug; where, never what", keys: ["error_class", "frames"] },
+    {
+        id: "events.dropped",
+        meaning: "the run reached its cap and counted the rest instead of writing them",
+        keys: ["dropped", "counts"],
+    },
     { id: "send.recorded", meaning: "a write the send guard saw, and how it ended", keys: ["outcome"] },
     { id: "job.start", meaning: "a background job started", keys: ["job"] },
     { id: "job.exit", meaning: "a background job ended", keys: ["job", "outcome"] },

package/dist/runs/recording.d.ts

@@ -18,6 +18,8 @@ export interface RecordingOptions {
     env?: NodeJS.ProcessEnv;
     runsDir?: string;
     keepDays?: number;
+    keepSuccessDays?: number;
+    maxBytes?: number;
     now?: () => Date;
     /** The caller's trace; otherwise the enclosing run's, otherwise `TRACEPARENT` from `env`. */
     traceId?: string;
@@ -27,13 +29,15 @@ export interface RecordingOptions {
      */
     processRun?: boolean;
     /** The whole command, its masked arguments and the agent that started it. */
-    context?: RunContext;
+    context?: RunContext & {
+        argvIfFailed?: string[];
+    };
 }
 /**
  * Runs one command with the diagnostics turned on, and **finalizes on every path**.
  *
- * `--trace` shows each event as it happens and keeps nothing, `--record` keeps it and shows
- * nothing. It is a wrapper rather than three lines in each command because the failure it prevents
+ * `--trace` shows each event as it happens; the run is kept as the config says — every run unless
+ * `record: false`, which keeps failures only. It is a wrapper rather than three lines in each command because the failure it prevents
  * is the quiet one: a run directory left saying `running` because the command threw on the way out.
  */
 export declare const recorded: <T>(options: RecordingOptions, body: (events: EventSink) => Promise<T>) => Promise<T>;
@@ -49,6 +53,9 @@ export interface Recording {
 /** `recorded` in two halves, for a caller that starts a run before its command and ends it after (max-cli's `max bot`). */
 export declare const startRecording: (options: RecordingOptions) => Recording;
 export declare const wasSettled: (error: unknown) => boolean;
+/** A run of a loop that never ends must not fill the disk: past these, events are counted by operation instead. */
+export declare const EVENTS_AT_MOST = 2000;
+export declare const EVENT_BYTES_AT_MOST: number;
 /**
  * Where a crash happened, not what it said: the class and up to ten frames as `function file:line`,
  * paths cut to the package's own (`framesOf`). **Never `message`** in an event — it can hold whatever the

package/dist/runs/recording.js

@@ -9,8 +9,8 @@ import { enclosingTraceId, inRun, traceOf, useAsProcessRun } from "./scope.js";
 /**
  * Runs one command with the diagnostics turned on, and **finalizes on every path**.
  *
- * `--trace` shows each event as it happens and keeps nothing, `--record` keeps it and shows
- * nothing. It is a wrapper rather than three lines in each command because the failure it prevents
+ * `--trace` shows each event as it happens; the run is kept as the config says — every run unless
+ * `record: false`, which keeps failures only. It is a wrapper rather than three lines in each command because the failure it prevents
  * is the quiet one: a run directory left saying `running` because the command threw on the way out.
  */
 export const recorded = async (options, body) => {
@@ -22,6 +22,7 @@ export const recorded = async (options, body) => {
             startedAt: Date.now(),
             ...(options.profile === undefined ? {} : { profile: options.profile }),
             ...(recording.traceId ? { traceId: recording.traceId } : {}),
+            events: recording.events,
         };
         if (options.processRun)
             useAsProcessRun(scope);
@@ -41,6 +42,7 @@ export const startRecording = (options) => {
     const startedAt = now();
     const runId = newRunId(startedAt, options.command);
     const traceId = options.traceId ?? enclosingTraceId() ?? traceOf(options.env ?? process.env).traceId;
+    const { argvIfFailed, ...context } = options.context ?? {};
     const open = (extra = {}) => startRun({
         runsDir: options.runsDir ?? runsDirFor(options.app, options.env),
         runId,
@@ -49,7 +51,7 @@ export const startRecording = (options) => {
         service: options.app.command,
         cliVersion: options.app.version,
         ...(traceId === undefined ? {} : { traceId }),
-        ...(options.context ? { context: options.context } : {}),
+        ...(options.context ? { context } : {}),
         // The operation has happened or is under way, and failing the command now invites a retry
         // that sends twice.
         onError: (error) => {
@@ -57,47 +59,65 @@ export const startRecording = (options) => {
             streams.diagnostic(options.format === "pretty" ? warning : JSON.stringify({ warning }));
         },
         ...(options.keepDays === undefined ? {} : { keepDays: options.keepDays }),
+        ...(options.keepSuccessDays === undefined ? {} : { keepSuccessDays: options.keepSuccessDays }),
+        ...(options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes }),
         now,
         ...extra,
     });
-    const run = options.record ? open({ startedAt }) : undefined;
+    const run = options.record ? open({ startedAt, lazy: true }) : undefined;
     // Unrecorded, the newest events are held until the outcome is known, so a failure can still be kept.
     const held = !run && options.keepFailed ? [] : undefined;
-    let requests = 0;
+    const counted = { wire: 0, operation: 0 };
     let refused;
+    const cap = capped();
+    const requests = () => (counted.wire > 0 ? counted.wire : counted.operation);
     const events = (event) => {
         if (event.event === "request")
-            requests += 1;
+            counted[event.level === "wire" ? "wire" : "operation"] += 1;
         if (event.event === "response" && event.outcome === "error")
             refused = event;
         if (options.trace)
             streams.diagnostic(options.format === "pretty" ? renderEvent(event) : JSON.stringify(logAttributes(event)));
         if (run)
-            logEvent(run, event);
+            cap.log(run, event);
         if (held) {
             held.push(event);
             if (held.length > HELD_AT_MOST)
                 held.shift();
         }
     };
+    const keep = (kept) => {
+        for (const event of held ?? [])
+            cap.log(kept, event);
+        return kept;
+    };
     return {
         runId,
         ...(traceId === undefined ? {} : { traceId }),
         events,
         succeed: async (answer) => {
             const partial = partialOutcome(answer);
-            const kept = run ?? (partial && held ? keep(open({ startedAt }), held) : undefined);
-            await kept?.finish(partial ? "partial" : "success", { requests, ...(partial ? { partial } : {}) });
+            const kept = run ?? (partial && held ? keep(open({ startedAt })) : undefined);
+            if (kept)
+                cap.close(kept);
+            await kept?.finish(partial ? "partial" : "success", {
+                requests: requests(),
+                ...cap.dropped(),
+                ...(partial ? { partial } : {}),
+            });
         },
         fail: async (error) => {
-            const failed = run ?? (held ? keep(open({ startedAt }), held) : undefined);
+            const failed = run ?? (held ? keep(open({ startedAt })) : undefined);
             if (failed) {
                 if (!isCliFailure(error))
                     failed.logger.error(crashOf(error));
+                cap.close(failed);
                 await failed.finish("failed", {
-                    requests,
+                    requests: requests(),
+                    ...cap.dropped(),
                     ...outcomeOf(error),
                     error: errorDetailOf(error, refused),
+                    ...(argvIfFailed ? { argv: argvIfFailed } : {}),
                     ...(run ? {} : { keptBecauseFailed: true }),
                 });
             }
@@ -110,10 +130,34 @@ export const startRecording = (options) => {
 const settled = new WeakSet();
 export const wasSettled = (error) => typeof error === "object" && error !== null && settled.has(error);
 const HELD_AT_MOST = 500;
-const keep = (run, events) => {
-    for (const event of events)
-        logEvent(run, event);
-    return run;
+/** A run of a loop that never ends must not fill the disk: past these, events are counted by operation instead. */
+export const EVENTS_AT_MOST = 2000;
+export const EVENT_BYTES_AT_MOST = 1024 * 1024;
+const capped = () => {
+    let lines = 0;
+    let bytes = 0;
+    let dropped = 0;
+    const byOperation = {};
+    return {
+        log: (run, event) => {
+            // The record's own envelope (time, ids of the run, resource) is about 200 bytes on top of its attributes.
+            const size = JSON.stringify(logAttributes(event)).length + 200;
+            if (lines >= EVENTS_AT_MOST || bytes + size > EVENT_BYTES_AT_MOST) {
+                dropped += 1;
+                const operation = "operation" in event && event.operation ? event.operation : event.event;
+                byOperation[operation] = (byOperation[operation] ?? 0) + 1;
+                return;
+            }
+            lines += 1;
+            bytes += size;
+            logEvent(run, event);
+        },
+        close: (run) => {
+            if (dropped > 0)
+                run.logger.warn({ event: "events.dropped", dropped, counts: byOperation });
+        },
+        dropped: () => (dropped > 0 ? { eventsDropped: dropped } : {}),
+    };
 };
 const logEvent = (run, event) => {
     const record = {

package/dist/runs/run-context.d.ts

@@ -7,7 +7,54 @@ export interface RunAgent {
     session_id: string | null;
     /** Set, and only `true`, when a chat message started the agent's turn; who sent it is never kept. */
     from_chat?: true;
+    /** The MCP client that made the call, as it named itself; `id` is `clientHash` of an OAuth client's id. */
+    client?: RunClient;
 }
+export interface RunClient {
+    name: string;
+    version?: string;
+    id?: string;
+}
+/** `record_input`: the words typed are kept (`true`), masked (`false`), or kept only in a run that failed. */
+export type RecordInput = boolean | "failed";
+/**
+ * Whether a run that succeeds is kept. Every run is, unless the config says `record: false` — then only failures —
+ * or WireCat Desktop ran the command for its own pages (`WIRECAT_CALLER=desktop`), or the command runs until stopped
+ * (`watch`, `serve`, `mcp`): those two only on `--record`. An MCP call is the caller's run, not Desktop's.
+ */
+export declare const keepsSuccess: ({ record, fromFlag, env, caller, persistent, }: {
+    record: boolean;
+    fromFlag: boolean;
+    env: NodeJS.ProcessEnv;
+    caller?: RunCaller | undefined;
+    persistent?: boolean;
+}) => boolean;
+/** How the run was asked for: typed or scripted, an MCP client on stdio or over HTTP, or WireCat Desktop. */
+export type RunVia = "cli" | "mcp-stdio" | "mcp-http" | "desktop";
+/** The MCP call a run answered. `connection_id` groups the calls of one connection when no agent session does. */
+export interface RunMcp {
+    tool: string;
+    request_id?: string;
+    connection_id?: string;
+    /** The every-profile server passed the call on; the caller is the one it named. */
+    proxied?: true;
+}
+/** Who asked for a run, worked out by whoever received the call; it wins over the process's environment. */
+export interface RunCaller {
+    via: RunVia;
+    agent?: RunAgent;
+    mcp?: RunMcp;
+}
+/**
+ * Runs one MCP call with its caller known, so every run opened under it names that caller: the command's own, and
+ * the connection a server opens for it, which runs under the server's context.
+ */
+export declare const withCaller: <T>(caller: RunCaller, work: () => T) => T;
+export declare const currentCaller: () => RunCaller | undefined;
+/** An OAuth client id is a bearer of sorts: a run keeps eight hex characters of its SHA-256, enough to tell apps apart. */
+export declare const clientHash: (id: string) => string;
+/** `WIRECAT_CALLER=desktop` is set by WireCat Desktop on the commands it runs for its own pages. */
+export declare const viaOf: (env: NodeJS.ProcessEnv) => RunVia;
 /**
  * The agent is read from what each one sets in the processes it starts: Claude Code `CLAUDECODE` and
  * `CLAUDE_CODE_SESSION_ID`, Codex `CODEX_THREAD_ID`, OpenCode `OPENCODE` and `OPENCODE_SESSION_ID`, Hermes
@@ -43,13 +90,17 @@ export declare const maskArgv: (program: Command, words: readonly string[], { ke
  * that calls `recorded` or `startRecording` for a command of its own passes this as `context`; without it the run
  * keeps no command line and no agent.
  */
-export declare const runContextOf: ({ bin, command, program, argv, env, recordInput, }: {
+export declare const runContextOf: ({ bin, command, program, argv, env, recordInput, caller, }: {
     bin: string;
     /** The run's own name, `messages list` or `mcp messages list`; empty when no command was recognised. */
     command: string;
     program?: Command;
     argv?: readonly string[];
     env: NodeJS.ProcessEnv;
-    /** The owner's `record_input`; left out, every value that may be content is masked. */
-    recordInput?: boolean;
-}) => RunContext;
+    /** The owner's `record_input`; left out, every value that may be content is masked. `failed` keeps them only then. */
+    recordInput?: RecordInput | undefined;
+    /** Who asked, when the receiver knows better than the environment: an MCP call. */
+    caller?: RunCaller | undefined;
+}) => RunContext & {
+    argvIfFailed?: string[];
+};

package/dist/runs/run-context.js

@@ -1,7 +1,34 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
 import { isContentKey } from "@wirecat/cli-base/standards";
 import { BARE_PHONE, INTERNATIONAL_PHONE } from "./error-detail.js";
 import { secretNamed, withoutSecrets } from "./secrets.js";
 export const REDACTED = "[redacted]";
+/**
+ * Whether a run that succeeds is kept. Every run is, unless the config says `record: false` — then only failures —
+ * or WireCat Desktop ran the command for its own pages (`WIRECAT_CALLER=desktop`), or the command runs until stopped
+ * (`watch`, `serve`, `mcp`): those two only on `--record`. An MCP call is the caller's run, not Desktop's.
+ */
+export const keepsSuccess = ({ record, fromFlag, env, caller, persistent = false, }) => {
+    if (!record)
+        return false;
+    if (fromFlag)
+        return true;
+    if (persistent)
+        return false;
+    return caller !== undefined || viaOf(env) !== "desktop";
+};
+const calls = new AsyncLocalStorage();
+/**
+ * Runs one MCP call with its caller known, so every run opened under it names that caller: the command's own, and
+ * the connection a server opens for it, which runs under the server's context.
+ */
+export const withCaller = (caller, work) => calls.run(caller, work);
+export const currentCaller = () => calls.getStore();
+/** An OAuth client id is a bearer of sorts: a run keeps eight hex characters of its SHA-256, enough to tell apps apart. */
+export const clientHash = (id) => createHash("sha256").update(id).digest("hex").slice(0, 8);
+/** `WIRECAT_CALLER=desktop` is set by WireCat Desktop on the commands it runs for its own pages. */
+export const viaOf = (env) => (env.WIRECAT_CALLER?.trim() === "desktop" ? "desktop" : "cli");
 /**
  * The agent is read from what each one sets in the processes it starts: Claude Code `CLAUDECODE` and
  * `CLAUDE_CODE_SESSION_ID`, Codex `CODEX_THREAD_ID`, OpenCode `OPENCODE` and `OPENCODE_SESSION_ID`, Hermes
@@ -176,13 +203,17 @@ const safeShape = (value) => (NUMBER.test(value) && !/^\d{11,}$/.test(value)) ||
  * that calls `recorded` or `startRecording` for a command of its own passes this as `context`; without it the run
  * keeps no command line and no agent.
  */
-export const runContextOf = ({ bin, command, program, argv, env, recordInput = false, }) => {
-    const masked = program && argv ? maskArgv(program, argv, { keep: recordInput }) : undefined;
-    const agent = agentOf(env);
+export const runContextOf = ({ bin, command, program, argv, env, recordInput = false, caller, }) => {
+    const masked = program && argv ? maskArgv(program, argv, { keep: recordInput === true }) : undefined;
+    const ifFailed = program && argv && recordInput === "failed" ? maskArgv(program, argv, { keep: true }) : undefined;
+    const agent = caller ? caller.agent : agentOf(env);
     return {
         cliCommand: command ? `${bin} ${command}` : bin,
         ...(masked ? { argv: masked.argv } : {}),
+        ...(ifFailed ? { argvIfFailed: ifFailed.argv } : {}),
         ...(masked?.unknownCommand === undefined ? {} : { unknownCommand: masked.unknownCommand }),
         ...(agent ? { agent } : {}),
+        via: caller?.via ?? viaOf(env),
+        ...(caller?.mcp ? { mcp: caller.mcp } : {}),
     };
 };

package/dist/runs/run.d.ts

@@ -1,7 +1,7 @@
 import { type Logger } from "@wirecat/cli-base";
 import type { AppIdentity } from "../ports/app.js";
 import type { RunError } from "./error-detail.js";
-import type { RunAgent } from "./run-context.js";
+import type { RunAgent, RunMcp, RunVia } from "./run-context.js";
 export type RunStatus = "success" | "failed" | "partial";
 /**
  * What a run was, and how it ended. **It never says what was read or sent** — a command, a profile,
@@ -18,8 +18,10 @@ export interface RunMetadata {
     startedAt: string;
     completedAt?: string;
     status: RunStatus | "running";
-    /** How many operations reached the messenger. */
+    /** How many calls reached the messenger: wire calls when the transport logs them, otherwise operations. */
     requests?: number;
+    /** Events past the run's cap, counted rather than written; an `events.dropped` line says which. */
+    eventsDropped?: number;
     durationMs?: number;
     cliVersion: string;
     /** `node 24.1.0` or `bun 1.3.14`, and where: what a problem report is asked for first. */
@@ -53,13 +55,17 @@ export interface RunMetadata {
     argv?: string[];
     /** The word that named no command, when that is why the run failed. */
     unknownCommand?: string;
-    /** The coding agent that started it, when one did. */
+    /** The coding agent that started it, when one did, and the MCP client that made the call. */
     agent?: RunAgent;
+    /** How it was asked for (`viaOf`, or the MCP server that received it). */
+    via?: RunVia;
+    /** The MCP call it answered. */
+    mcp?: RunMcp;
     /** How a failed run failed (`errorDetailOf`). */
     error?: RunError;
 }
 /** Who started a run and with what, known before it starts. */
-export type RunContext = Pick<RunMetadata, "cliCommand" | "argv" | "unknownCommand" | "agent">;
+export type RunContext = Pick<RunMetadata, "cliCommand" | "argv" | "unknownCommand" | "agent" | "via" | "mcp">;
 export interface StartRunOptions {
     runsDir: string;
     command: string;
@@ -69,6 +75,15 @@ export interface StartRunOptions {
     cliVersion: string;
     /** Older runs are removed as this one starts. */
     keepDays?: number;
+    /** Successful runs older than this are removed sooner than the failures `keepDays` keeps. */
+    keepSuccessDays?: number;
+    /** The runs folder's size limit in bytes: past it, the oldest successful runs go first, then the oldest days. */
+    maxBytes?: number;
+    /**
+     * Opens the directory only when there is something to put in it: an event, or an ending other than a plain
+     * success. A success with no events is then one line in the day's index (`runs show` reads it from there).
+     */
+    lazy?: boolean;
     runId?: string;
     now?: () => Date;
     /** When the command began, if that was before the run was opened — a failure kept after the fact. */
@@ -90,6 +105,8 @@ export interface Run {
     finish(status: RunStatus, extra?: Partial<RunMetadata>): Promise<void>;
 }
 export declare const KEEP_RUNS_FOR_DAYS = 30;
+export declare const KEEP_SUCCESSFUL_RUNS_FOR_DAYS = 7;
+export declare 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 declare const runsDirFor: (app: AppIdentity, env?: NodeJS.ProcessEnv) => string;
 /**
@@ -101,14 +118,19 @@ export declare const runsDirFor: (app: AppIdentity, env?: NodeJS.ProcessEnv) =>
  *   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 declare const startRun: (options: StartRunOptions) => Run;
+/**
+ * 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 declare const refuseRealStateInTests: (dir: string, env?: NodeJS.ProcessEnv) => void;
 export declare const runtime: () => string;
 /** `20260920T084431Z-chats-list-a81f2c` — sortable, and readable without opening it. */
 export declare const newRunId: (startedAt: Date, command: string) => string;
@@ -138,12 +160,16 @@ export declare const findRun: (runsDir: string, id: string) => {
  */
 export declare const readEvents: (dir: string) => Record<string, unknown>[];
 /**
- * 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 declare const pruneRuns: (runsDir: string, { keepDays, now }: {
+export declare const pruneRuns: (runsDir: string, { keepDays, keepSuccessDays, maxBytes, now, }: {
     keepDays: number;
+    keepSuccessDays?: number;
+    maxBytes?: number;
     now: Date;
 }) => number;