@wirecat/cli-core 0.424.0 → 0.425.0

package/dist/meetings/mcp/search.js

@@ -1,12 +1,12 @@
 import { CliError, errorObjectOf, isCliError, mcpErrorResult } from "@wirecat/cli-base";
 import { meetingHitsList } from "../answers.js";
 import { validateMeetingHitSearch } from "../search-validation.js";
-import { agentResult, UNTRUSTED } from "./agent-text.js";
+import { agentResult, UNTRUSTED_NEUTRAL } from "./agent-text.js";
 const integer = { type: "integer", minimum: 1, maximum: Number.MAX_SAFE_INTEGER };
 const name = { type: "string", minLength: 1, maxLength: 200 };
 export const meetingSearchTool = {
     name: "search_meetings",
-    description: `Find words in the selected account's stored meetings, indexing new ones first; participant filters do not say who spoke a hit. ${UNTRUSTED}`,
+    description: `Find words in the selected account's stored meetings, indexing new ones first; participant filters do not say who spoke a hit. ${UNTRUSTED_NEUTRAL}`,
     annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
     inputSchema: {
         type: "object",

package/dist/runs/error-detail.d.ts

@@ -0,0 +1,42 @@
+import { type RequestEvent } from "./events.js";
+/**
+ * What went wrong, for the owner reading a failed run: the class, the code, the sentence with anything that can be
+ * somebody's words masked, where the call went, and where in our code it broke. Keys as written in run.json.
+ */
+export interface RunError {
+    class: string;
+    code?: string;
+    reason?: string;
+    message?: string;
+    /** Ours, not the messenger's: `messages.send`. */
+    operation?: string;
+    http?: {
+        method?: string;
+        endpoint_template?: string;
+        status?: number;
+    };
+    /** A messenger protocol's refusal: `FLOOD_WAIT`, and its numeric code when it has one (MTProto's 420). */
+    provider?: {
+        key?: string;
+        code?: number;
+    };
+    causes?: {
+        class: string;
+        message?: string;
+    }[];
+    stack?: string[];
+}
+export declare const errorDetailOf: (error: unknown, response?: RequestEvent) => RunError;
+/** `function file:line`, as `command.crashed` writes them: the package's own path, never the home directory. */
+export declare const framesOf: (error: unknown, limit?: number) => string[];
+/**
+ * Where a request went, with nothing in it that names a person or opens an account: no query string, no user, an id
+ * or a token in the path as `:id` / `:token`. The host stays — which service refused is the point.
+ */
+export declare const endpointTemplate: (raw: string) => string;
+/**
+ * An error's sentence with what could be somebody's words or a secret taken out: anything in quotes, an email, a
+ * phone number, a bot token, a bearer or a long opaque string, a URL's query, the home directory. A second line of
+ * defence — errors here are written to name things, not quote them — so it errs toward masking.
+ */
+export declare const redactText: (text: string) => string;

package/dist/runs/error-detail.js

@@ -0,0 +1,131 @@
+import { homedir } from "node:os";
+import { isCliFailure } from "../errors/failures.js";
+import { providerErrorKey } from "./events.js";
+const MESSAGE_AT_MOST = 500;
+const CAUSES_AT_MOST = 5;
+const FRAMES_AT_MOST = 15;
+export const errorDetailOf = (error, response) => {
+    const details = isCliFailure(error) ? { ...error.details } : {};
+    const thrown = error instanceof Error ? error : undefined;
+    const code = isCliFailure(error) ? error.code : codeOf(error);
+    const reason = typeof details.reason === "string" ? details.reason : undefined;
+    const message = thrown ? redactText(thrown.message) : undefined;
+    const operation = stringOf(details.operation) ?? response?.operation;
+    const status = numberOf(details.status) ?? response?.status;
+    const method = stringOf(details.method) ?? response?.method;
+    const endpoint = stringOf(details.endpoint) ?? response?.endpointTemplate;
+    const key = providerErrorKey(details.provider_error) ?? providerErrorKey(response?.providerError);
+    const protocol = key !== undefined && method === undefined && endpoint === undefined;
+    const http = method !== undefined || endpoint !== undefined || (status !== undefined && !protocol)
+        ? {
+            ...(method === undefined ? {} : { method: method.toUpperCase().slice(0, 16) }),
+            ...(endpoint === undefined ? {} : { endpoint_template: endpointTemplate(endpoint) }),
+            ...(status === undefined ? {} : { status }),
+        }
+        : undefined;
+    const causes = causesOf(thrown?.cause ?? details.cause);
+    const stack = framesOf(thrown);
+    return {
+        class: classOf(error),
+        ...(code === undefined ? {} : { code }),
+        ...(reason === undefined ? {} : { reason }),
+        ...(message ? { message } : {}),
+        ...(operation === undefined ? {} : { operation }),
+        ...(http ? { http } : {}),
+        ...(key === undefined ? {} : { provider: { key, ...(protocol && status !== undefined ? { code: status } : {}) } }),
+        ...(causes.length > 0 ? { causes } : {}),
+        ...(stack.length > 0 ? { stack } : {}),
+    };
+};
+const stringOf = (value) => typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+const numberOf = (value) => typeof value === "number" && Number.isInteger(value) ? value : undefined;
+const classOf = (error) => {
+    if (!(error instanceof Error))
+        return error === null ? "null" : typeof error;
+    const constructed = error.constructor?.name;
+    return constructed && constructed !== "Error" && constructed !== error.name ? constructed : error.name;
+};
+/** `ECONNRESET`, `commander.unknownCommand`, `ERR_INVALID_ARG_TYPE` — a code a program set, never a sentence. */
+const codeOf = (error) => {
+    const code = error?.code;
+    return typeof code === "string" && /^[A-Za-z][A-Za-z0-9._-]{0,63}$/.test(code) ? code : undefined;
+};
+const causesOf = (first) => {
+    const causes = [];
+    const seen = new Set();
+    for (let cause = first; cause !== undefined && cause !== null && causes.length < CAUSES_AT_MOST;) {
+        if (seen.has(cause))
+            break;
+        seen.add(cause);
+        const message = cause instanceof Error ? redactText(cause.message) : undefined;
+        causes.push({ class: classOf(cause), ...(message ? { message } : {}) });
+        cause = cause instanceof Error ? cause.cause : undefined;
+    }
+    return causes;
+};
+/** `function file:line`, as `command.crashed` writes them: the package's own path, never the home directory. */
+export const framesOf = (error, limit = FRAMES_AT_MOST) => {
+    const stack = error instanceof Error && typeof error.stack === "string" ? error.stack : "";
+    return stack
+        .split("\n")
+        .filter((line) => line.trimStart().startsWith("at "))
+        .flatMap((line) => {
+        const match = /^\s*at (?:async )?(?:(.+?) \()?(.+?):(\d+):\d+\)?$/.exec(line);
+        if (!match)
+            return [];
+        const [, fn, path = "", lineNumber] = match;
+        if (path.startsWith("node:"))
+            return [];
+        return [`${fn ?? "<anonymous>"} ${fileOf(path)}:${lineNumber}`];
+    })
+        .slice(0, limit);
+};
+const fileOf = (path) => {
+    const plain = path.replace(/^file:\/\//, "");
+    const packaged = /\/node_modules\/((?:@[^/]+\/)?[^/]+\/.+)$/.exec(plain)?.[1];
+    if (packaged)
+        return packaged.replace(/\/(?:dist|src)\//, "/");
+    return /(?:^|\/)(?:dist|src)\/(.+)$/.exec(plain)?.[1] ?? plain.split("/").at(-1) ?? "?";
+};
+/**
+ * Where a request went, with nothing in it that names a person or opens an account: no query string, no user, an id
+ * or a token in the path as `:id` / `:token`. The host stays — which service refused is the point.
+ */
+export const endpointTemplate = (raw) => {
+    const trimmed = raw.trim().split(/[?#]/)[0] ?? "";
+    const origin = /^[a-z][a-z0-9+.-]*:\/\/(?:[^@/]*@)?([^/]*)/i.exec(trimmed);
+    const path = origin ? trimmed.slice(origin[0].length) : trimmed;
+    const scheme = origin ? `${trimmed.slice(0, trimmed.indexOf("://"))}://${origin[1]}` : "";
+    const segments = path.split("/").map((segment) => {
+        if (segment === "" || /^[:{].+/.test(segment))
+            return segment;
+        if (/^bot\d+:/.test(segment) || /^\d{6,}:[\w-]{20,}$/.test(segment))
+            return ":token";
+        if (/^-?\d+$/.test(segment) || /^[0-9a-f-]{16,}$/i.test(segment))
+            return ":id";
+        if (!/^[A-Za-z0-9._~-]{1,40}$/.test(segment))
+            return ":value";
+        return segment;
+    });
+    return `${scheme}${segments.join("/")}`.slice(0, 300);
+};
+/**
+ * An error's sentence with what could be somebody's words or a secret taken out: anything in quotes, an email, a
+ * phone number, a bot token, a bearer or a long opaque string, a URL's query, the home directory. A second line of
+ * defence — errors here are written to name things, not quote them — so it errs toward masking.
+ */
+export const redactText = (text) => {
+    const home = homedir();
+    let out = home && home !== "/" ? text.split(home).join("~") : text;
+    out = out
+        .replace(/"[^"\n]*"|“[^”\n]*”|«[^»\n]*»/g, '"[redacted]"')
+        .replace(/\b(bearer|basic|token|key|password|secret)(\s*[:=]?\s+)\S+/gi, "$1$2[redacted]")
+        .replace(/[\w.+-]+@[\w-]+\.[\w.-]+/g, "[email]")
+        .replace(/\+\d[\d\s()-]{6,}\d/g, "[number]")
+        .replace(/(^|[^\w-])\d{11,15}\b/g, "$1[number]")
+        .replace(/\bbot\d+:[\w-]+/g, "bot[token]")
+        .replace(/\b\d{6,}:[\w-]{20,}\b/g, "[token]")
+        .replace(/(\?|&)[^\s#]*/g, "$1[redacted]")
+        .replace(/\b[A-Za-z0-9_-]{40,}\b/g, "[redacted]");
+    return out.length > MESSAGE_AT_MOST ? `${out.slice(0, MESSAGE_AT_MOST)}…` : out;
+};

package/dist/runs/events.d.ts

@@ -15,6 +15,10 @@ export interface RequestEvent {
     opcode?: number;
     seq?: number;
     status?: number;
+    /** An HTTP API's verb, `POST`. */
+    method?: string;
+    /** The path it went to with ids as `:id` and no query string — `/chats/:id/messages`. Never the URL as sent. */
+    endpointTemplate?: string;
     /** The size of what went out or came back. */
     bytes?: number;
     ids?: Record<string, string>;

package/dist/runs/events.js

@@ -24,6 +24,8 @@ export const renderEvent = (event) => {
     else {
         if (event.opcode !== undefined)
             parts.push(`op ${event.opcode}`, `seq ${event.seq}`);
+        if (event.method !== undefined || event.endpointTemplate !== undefined)
+            parts.push([event.method, event.endpointTemplate].filter(Boolean).join(" "));
         if (event.status !== undefined)
             parts.push(`${event.status}`);
     }

package/dist/runs/log-attributes.js

@@ -7,6 +7,8 @@ const diagnostic = {
     opcode: true,
     seq: true,
     status: true,
+    method: true,
+    endpointTemplate: true,
     bytes: true,
     ids: true,
     counts: true,

package/dist/runs/recording.d.ts

@@ -1,6 +1,7 @@
 import { type RenderFormat, type Streams } from "@wirecat/cli-base";
 import type { AppIdentity } from "../ports/app.js";
 import { type EventSink } from "./events.js";
+import { type RunContext } from "./run.js";
 export interface RecordingOptions {
     app: AppIdentity;
     /** As typed, without the arguments: `chats list`. It names the run directory. */
@@ -25,6 +26,8 @@ export interface RecordingOptions {
      * that answer's `meta.run_id` name the run `runs show` finds. Never in a server, where runs overlap.
      */
     processRun?: boolean;
+    /** The whole command, its masked arguments and the agent that started it. */
+    context?: RunContext;
 }
 /**
  * Runs one command with the diagnostics turned on, and **finalizes on every path**.
@@ -48,8 +51,8 @@ export declare const startRecording: (options: RecordingOptions) => Recording;
 export declare const wasSettled: (error: unknown) => boolean;
 /**
  * Where a crash happened, not what it said: the class and up to ten frames as `function file:line`,
- * paths cut to what follows `dist/` or `src/`. **Never `message`** — it can hold whatever the
- * failing line was handling.
+ * paths cut to the package's own (`framesOf`). **Never `message`** in an event — it can hold whatever the
+ * failing line was handling; run.json's `error` keeps it, masked.
  */
 export declare const crashOf: (error: unknown) => {
     event: "command.crashed";

package/dist/runs/recording.js

@@ -1,5 +1,6 @@
 import { processStreams } from "@wirecat/cli-base";
 import { isCliFailure } from "../errors/failures.js";
+import { endpointTemplate, errorDetailOf, framesOf } from "./error-detail.js";
 import { providerErrorKey, renderEvent } from "./events.js";
 import { DIAGNOSTIC_LOG_EVENTS } from "./log-events.js";
 import { logAttributes } from "./log-keys.js";
@@ -48,6 +49,7 @@ export const startRecording = (options) => {
         service: options.app.command,
         cliVersion: options.app.version,
         ...(traceId === undefined ? {} : { traceId }),
+        ...(options.context ? { context: options.context } : {}),
         // The operation has happened or is under way, and failing the command now invites a retry
         // that sends twice.
         onError: (error) => {
@@ -62,9 +64,12 @@ export const startRecording = (options) => {
     // 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;
+    let refused;
     const events = (event) => {
         if (event.event === "request")
             requests += 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)
@@ -92,6 +97,7 @@ export const startRecording = (options) => {
                 await failed.finish("failed", {
                     requests,
                     ...outcomeOf(error),
+                    error: errorDetailOf(error, refused),
                     ...(run ? {} : { keptBecauseFailed: true }),
                 });
             }
@@ -110,7 +116,13 @@ const keep = (run, events) => {
     return run;
 };
 const logEvent = (run, event) => {
-    const record = { ...event, event: DIAGNOSTIC_LOG_EVENTS[event.event] };
+    const record = {
+        ...event,
+        event: DIAGNOSTIC_LOG_EVENTS[event.event],
+        ...("endpointTemplate" in event && event.endpointTemplate !== undefined
+            ? { endpointTemplate: endpointTemplate(event.endpointTemplate) }
+            : {}),
+    };
     if (event.event === "warning")
         run.logger.warn(record);
     else if (event.event !== "cache" && event.outcome === "error")
@@ -126,25 +138,14 @@ const outcomeOf = (error) => {
 };
 /**
  * Where a crash happened, not what it said: the class and up to ten frames as `function file:line`,
- * paths cut to what follows `dist/` or `src/`. **Never `message`** — it can hold whatever the
- * failing line was handling.
+ * paths cut to the package's own (`framesOf`). **Never `message`** in an event — it can hold whatever the
+ * failing line was handling; run.json's `error` keeps it, masked.
  */
-export const crashOf = (error) => {
-    const stack = error instanceof Error && typeof error.stack === "string" ? error.stack : "";
-    const frames = stack
-        .split("\n")
-        .filter((line) => line.trimStart().startsWith("at "))
-        .slice(0, 10)
-        .map((line) => {
-        const match = /^\s*at (?:(.+?) \()?(.+?):(\d+):\d+\)?$/.exec(line);
-        if (!match)
-            return "?";
-        const [, fn, path = "", lineNumber] = match;
-        const file = /(?:^|\/)(?:dist|src)\/(.+)$/.exec(path)?.[1] ?? path.split("/").at(-1);
-        return `${fn ?? "<anonymous>"} ${file}:${lineNumber}`;
-    });
-    return { event: "command.crashed", errorClass: error instanceof Error ? error.name : typeof error, frames };
-};
+export const crashOf = (error) => ({
+    event: "command.crashed",
+    errorClass: error instanceof Error ? error.name : typeof error,
+    frames: framesOf(error, 10),
+});
 export const partialOutcome = (answer) => {
     if (!answer || typeof answer !== "object")
         return undefined;

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

@@ -0,0 +1,37 @@
+import type { Command } from "commander";
+import type { RunContext } from "./run.js";
+export declare const REDACTED = "[redacted]";
+/** Which coding agent started the process, and its session when the agent names one. Keys as written in run.json. */
+export interface RunAgent {
+    kind: string;
+    session_id: string | null;
+}
+/**
+ * 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`, Gemini CLI
+ * `GEMINI_CLI`, Cursor `CURSOR_AGENT` — the last two give their commands no session id. `AI_AGENT` (Claude Code,
+ * OpenCode) carries a version, `claude-code_2-1-296_agent`, so only the name before it is kept.
+ */
+export declare const agentOf: (env: NodeJS.ProcessEnv) => RunAgent | undefined;
+export interface MaskedArgv {
+    /** The words after the binary, every value that may be content or a secret replaced by `[redacted]`. */
+    argv: string[];
+    /** The first word that names no command where one was expected. */
+    unknownCommand?: string;
+}
+/**
+ * The command line as typed, safe to keep. Command words, flag names and the profile stay; a value stays only when
+ * its shape cannot be somebody's words — a number short of a phone's length, a duration, a date, `true`, one of the
+ * option's declared choices — and its option or argument is not named for content (`--text`, `<phone>`). Anything
+ * else, a positional after `--` or an argument no command declares, is `[redacted]`: a chat is often typed by title.
+ */
+export declare const maskArgv: (program: Command, words: readonly string[]) => MaskedArgv;
+/** A run's context from the parsed program: `max messages list` and its masked words, or the word that named nothing. */
+export declare const runContextOf: ({ bin, command, program, argv, env, }: {
+    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;
+}) => RunContext;

package/dist/runs/run-context.js

@@ -0,0 +1,148 @@
+import { isContentKey } from "@wirecat/cli-base/standards";
+export const REDACTED = "[redacted]";
+/**
+ * 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`, Gemini CLI
+ * `GEMINI_CLI`, Cursor `CURSOR_AGENT` — the last two give their commands no session id. `AI_AGENT` (Claude Code,
+ * OpenCode) carries a version, `claude-code_2-1-296_agent`, so only the name before it is kept.
+ */
+export const agentOf = (env) => {
+    const named = env.AI_AGENT?.trim().split("_")[0];
+    const kind = (named && plainWord(named) ? named.toLowerCase() : undefined) ??
+        (env.CLAUDECODE ? "claude-code" : undefined) ??
+        (env.CODEX_THREAD_ID || env.CODEX_SESSION_ID || env.CODEX_SANDBOX ? "codex" : undefined) ??
+        (env.GEMINI_CLI ? "gemini-cli" : undefined) ??
+        (env.OPENCODE ? "opencode" : undefined) ??
+        (env.CURSOR_AGENT ? "cursor" : undefined);
+    if (!kind)
+        return undefined;
+    const session = sessionOf(kind, env);
+    return { kind, session_id: session && SESSION.test(session) ? session : null };
+};
+const SESSION = /^[A-Za-z0-9._:-]{1,128}$/;
+const sessionOf = (kind, env) => {
+    const value = kind === "claude-code"
+        ? env.CLAUDE_CODE_SESSION_ID
+        : kind === "codex"
+            ? env.CODEX_THREAD_ID
+            : kind === "opencode"
+                ? env.OPENCODE_SESSION_ID
+                : undefined;
+    return value?.trim() || undefined;
+};
+const plainWord = (word) => /^[A-Za-z][A-Za-z0-9.-]{0,39}$/.test(word);
+/**
+ * The command line as typed, safe to keep. Command words, flag names and the profile stay; a value stays only when
+ * its shape cannot be somebody's words — a number short of a phone's length, a duration, a date, `true`, one of the
+ * option's declared choices — and its option or argument is not named for content (`--text`, `<phone>`). Anything
+ * else, a positional after `--` or an argument no command declares, is `[redacted]`: a chat is often typed by title.
+ */
+export const maskArgv = (program, words) => {
+    const argv = [];
+    let unknownCommand;
+    let current = program;
+    let positional = 0;
+    let profileSeen = false;
+    let lost = false;
+    const optionFor = (flag) => {
+        for (let at = current; at; at = at.parent) {
+            const found = at.options.find((option) => option.long === flag || option.short === flag);
+            if (found)
+                return found;
+        }
+        return undefined;
+    };
+    for (let at = 0; at < words.length; at++) {
+        const word = words[at];
+        if (word === "--") {
+            argv.push("--");
+            for (let after = at + 1; after < words.length; after++)
+                argv.push(REDACTED);
+            break;
+        }
+        if (word.startsWith("-") && word.length > 1 && !NUMBER.test(word)) {
+            const equals = word.indexOf("=");
+            const flag = equals > 0 ? word.slice(0, equals) : word;
+            if (!/^--?[A-Za-z0-9][A-Za-z0-9-]*$/.test(flag)) {
+                argv.push(REDACTED);
+                continue;
+            }
+            const option = optionFor(flag);
+            const name = option?.attributeName() ?? flag.replace(/^-+/, "");
+            if (equals > 0) {
+                argv.push(`${flag}=${maskedValue(name, word.slice(equals + 1), option?.argChoices)}`);
+                continue;
+            }
+            argv.push(flag);
+            if (!option || !(option.required || option.optional))
+                continue;
+            const takes = (next) => next !== undefined && (option.required || !next.startsWith("-") || NUMBER.test(next));
+            if (takes(words[at + 1])) {
+                at += 1;
+                argv.push(maskedValue(name, words[at], option.argChoices));
+                while (option.variadic && words[at + 1] !== undefined && !words[at + 1].startsWith("-")) {
+                    at += 1;
+                    argv.push(maskedValue(name, words[at], option.argChoices));
+                }
+            }
+            continue;
+        }
+        if (!lost && positional === 0) {
+            const sub = current.commands.find((one) => one.name() === word || one.aliases().includes(word));
+            if (sub) {
+                argv.push(word);
+                current = sub;
+                continue;
+            }
+            if (current === program && !profileSeen) {
+                profileSeen = true;
+                argv.push(PROFILE.test(word) ? word : REDACTED);
+                continue;
+            }
+            if (current.commands.length > 0 && current.registeredArguments.length === 0) {
+                lost = true;
+                unknownCommand = commandLike(word);
+                argv.push(unknownCommand);
+                continue;
+            }
+        }
+        const declared = lost ? undefined : current.registeredArguments;
+        const argument = declared?.[Math.min(positional, declared.length - 1)];
+        positional += 1;
+        argv.push(argument ? maskedValue(argument.name(), word, argument.argChoices) : REDACTED);
+    }
+    return { argv, ...(unknownCommand === undefined ? {} : { unknownCommand }) };
+};
+const NUMBER = /^-?\d+(\.\d+)?$/;
+const PROFILE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** A mistyped command word is kept so the typo can be seen; anything shaped like a sentence or an address is not. */
+const commandLike = (word) => (/^[a-z][a-z0-9-]{0,31}$/i.test(word) ? word : REDACTED);
+const maskedValue = (name, value, choices) => {
+    if (isContentKey(name))
+        return REDACTED;
+    if (name === "profile")
+        return PROFILE.test(value) ? value : REDACTED;
+    if (name === "json" || name === "fields")
+        return /^[a-z0-9_.,]{1,200}$/.test(value) ? value : REDACTED;
+    if (choices?.includes(value))
+        return value;
+    return safeShape(value) ? value : REDACTED;
+};
+// A positive run of eleven or more digits can be a phone number written without its "+"; ids that long are negative
+// (chats and channels) and stay.
+const safeShape = (value) => (NUMBER.test(value) && !/^\d{11,}$/.test(value)) ||
+    /^\d+(ms|s|m|h|d|w)$/.test(value) ||
+    /^\d{4}-\d{2}-\d{2}([T ]\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:?\d{2})?)?$/.test(value) ||
+    value === "true" ||
+    value === "false";
+/** A run's context from the parsed program: `max messages list` and its masked words, or the word that named nothing. */
+export const runContextOf = ({ bin, command, program, argv, env, }) => {
+    const masked = program && argv ? maskArgv(program, argv) : undefined;
+    const agent = agentOf(env);
+    return {
+        cliCommand: command ? `${bin} ${command}` : bin,
+        ...(masked ? { argv: masked.argv } : {}),
+        ...(masked?.unknownCommand === undefined ? {} : { unknownCommand: masked.unknownCommand }),
+        ...(agent ? { agent } : {}),
+    };
+};

package/dist/runs/run.d.ts

@@ -1,10 +1,13 @@
 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";
 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
- * and a count, and the `errorCode` a script branches on rather than the sentence a person reads,
- * because a messenger's refusal can quote the payload back.
+ * What a run was, and how it ended. **It never says what was read or sent** — a command, a profile,
+ * a count, the arguments with every value that may be content masked, and the `errorCode` a script
+ * branches on. The sentence a person reads is kept only in `error`, masked, because a messenger's
+ * refusal can quote the payload back.
  */
 export interface RunMetadata {
     runId: string;
@@ -44,7 +47,19 @@ export interface RunMetadata {
     codes?: string[];
     /** The caller's trace: the MCP client's, or the schedule's or job's that started it. */
     traceId?: string;
+    /** The whole command with the program's name, `max messages list`; `command` stays the run's short name. */
+    cliCommand?: string;
+    /** The words after the program's name, every value that may be content or a secret `[redacted]` (`maskArgv`). */
+    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. */
+    agent?: RunAgent;
+    /** 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 interface StartRunOptions {
     runsDir: string;
     command: string;
@@ -60,6 +75,7 @@ export interface StartRunOptions {
     startedAt?: Date;
     /** The caller's trace, written on every record as `trace_id`. */
     traceId?: string;
+    context?: RunContext;
     /** The log file could not be opened or written; the run goes on unrecorded from here. */
     onError?: (error: Error) => void;
 }

package/dist/runs/run.js

@@ -74,6 +74,7 @@ export const startRun = (options) => {
         platform: process.platform,
         arch: process.arch,
         ...(options.traceId === undefined ? {} : { traceId: options.traceId }),
+        ...options.context,
     };
     writeRunFile(dir, metadata);
     let finished = false;

package/dist/store/exports.d.ts

@@ -32,6 +32,7 @@ export { OTHER_SOURCES, type OtherSource, type SourceMention } from "./sqlite/me
 export { MENTION_QUERY, MENTION_STATUSES, type MentionDecision, type MentionStatus, type MentionsRebuild, type MentionsState, type StoredMention, type StoredPlace, } from "./sqlite/mentions.js";
 export { drainNoteIndex, noteIndexState, resetNoteIndex } from "./sqlite/note-index.js";
 export type { Link as ThingLink } from "./sqlite/notes.js";
+export { openSqlite } from "./sqlite/open.js";
 export type { PersonPreparationRead, PreparationFact, PreparationNote, PreparationTask, } from "./sqlite/person-preparation.js";
 export { savedPhoneCountries, saveStorePhoneCountries } from "./sqlite/phone-countries.js";
 export type { PrivateContact, PrivateContactNote } from "./sqlite/private-people.js";
@@ -46,6 +47,7 @@ export { fillSearchIndex, resetSearchIndex, searchIndexState } from "./sqlite/se
 export type { SearchCommand, SearchRecord, StoredSearch } from "./sqlite/searches.js";
 export { type StemsState, savedStemmers, stemmerCache, stemmersOrigin, stemsState, } from "./sqlite/stems.js";
 export { fillStems, resetStems } from "./sqlite/stems-fill.js";
+export { rowCounts, storeContents } from "./sqlite/store-contents.js";
 export type { StoredTag, TagFilter, TagTarget, TaskTagTarget } from "./sqlite/tags.js";
 export { savedTaskCategories } from "./sqlite/task-category-settings.js";
 export { DEFAULT_AGENT_CLOSE, savedAgentClose } from "./sqlite/task-close.js";

package/dist/store/exports.js

@@ -11,12 +11,14 @@ export { involvementStoreOver } from "./sqlite/involvements.js";
 export { OTHER_SOURCES } from "./sqlite/mention-sources.js";
 export { MENTION_QUERY, MENTION_STATUSES, } from "./sqlite/mentions.js";
 export { drainNoteIndex, noteIndexState, resetNoteIndex } from "./sqlite/note-index.js";
+export { openSqlite } from "./sqlite/open.js";
 export { savedPhoneCountries, saveStorePhoneCountries } from "./sqlite/phone-countries.js";
 export { queryFilter } from "./sqlite/query-filter.js";
 export { AGENDA_COLUMNS } from "./sqlite/reads.js";
 export { fillSearchIndex, resetSearchIndex, searchIndexState } from "./sqlite/search-index.js";
 export { savedStemmers, stemmerCache, stemmersOrigin, stemsState, } from "./sqlite/stems.js";
 export { fillStems, resetStems } from "./sqlite/stems-fill.js";
+export { rowCounts, storeContents } from "./sqlite/store-contents.js";
 export { savedTaskCategories } from "./sqlite/task-category-settings.js";
 export { DEFAULT_AGENT_CLOSE, savedAgentClose } from "./sqlite/task-close.js";
 export { DEFAULT_FIRST_PASS_PER_CHAT, firstPassPerChatOf, savedFirstPassPerChat } from "./sqlite/task-first-pass.js";

package/dist/store/sqlite/store-contents.d.ts

@@ -0,0 +1,47 @@
+import type { CacheDatabase } from "../driver.js";
+/** The tables `store info` counts; a file from before a table's migration simply lacks it. */
+export declare const COUNTED_TABLES: readonly ["accounts", "chats", "messages", "emails", "documents", "meetings", "events", "attachments", "identities"];
+export declare const hasTable: (database: CacheDatabase, table: string) => boolean;
+export declare const rowCounts: (database: CacheDatabase) => Partial<Record<(typeof COUNTED_TABLES)[number], number>>;
+/**
+ * What the store holds, grouped, over every account in it. Plain `count(*) … GROUP BY` on indexed
+ * columns only: `dbstat` would give sizes per table but reads every page of the file.
+ */
+export declare const storeContents: (database: CacheDatabase) => {
+    byProvider: {
+        accounts: number;
+        provider: string;
+        chats: number;
+        documents: number;
+        emails: number;
+        meetings: number;
+        messages: number;
+    }[];
+    byChatKind: {
+        provider: string;
+        kind: string;
+        chats: number;
+        messages: number;
+    }[];
+    byAccount: {
+        provider: string;
+        accountId: number;
+        name: string | null;
+        chats: number;
+        documents: number;
+        emails: number;
+        meetings: number;
+        messages: number;
+    }[];
+    byYear: {
+        provider: string;
+        year: number;
+        messages: number;
+    }[];
+    byAttachmentKind: {
+        type: string;
+        kind: string;
+        count: number;
+        bytes: number;
+    }[];
+} | undefined;