@leemour/max-cli 0.1.0

package/dist/runs/events.js

@@ -0,0 +1,85 @@
+/**
+ * The ids a request named, by name, from a list of fields that is written out here.
+ *
+ * **An allowlist, never a filter.** Copying the request and removing what looks dangerous means a
+ * field nobody has seen yet arrives in the log by default; this way it cannot. `token` is the case
+ * that matters: it is a field of `session.login` and there is no branch here that could reach it.
+ */
+export const idsOf = (request) => {
+    if (!isRecord(request))
+        return {};
+    const ids = {};
+    const counts = {};
+    if (isId(request.chatId))
+        ids.chat = String(request.chatId);
+    if (isId(request.messageId))
+        ids.message = String(request.messageId);
+    if (typeof request.cid === "number")
+        ids.cid = String(request.cid);
+    // `messages.send` carries its client id one level down, and the `cid` is the one thing that makes
+    // an ambiguous send repeatable — see `MaxClient.messages.send`.
+    const message = isRecord(request.message) ? request.message : undefined;
+    if (message && typeof message.cid === "number")
+        ids.cid = String(message.cid);
+    if (Array.isArray(request.contactIds))
+        counts.contacts = request.contactIds.length;
+    return {
+        ...(Object.keys(ids).length > 0 ? { ids } : {}),
+        ...(Object.keys(counts).length > 0 ? { counts } : {}),
+    };
+};
+/**
+ * How many of each list MAX sent back — `{ chats: 25, contacts: 6 }`.
+ *
+ * Every array at the top of the answer, counted. Generic on purpose: a per-operation table of
+ * "which field is the interesting one" is a second registry to keep in step with `src/spec/`, and
+ * a field name with a length beside it is content-free whatever MAX adds next.
+ */
+export const countsIn = (payload) => {
+    const counts = {};
+    for (const [field, value] of Object.entries(payload))
+        if (Array.isArray(value))
+            counts[field] = value.length;
+    return Object.keys(counts).length > 0 ? counts : undefined;
+};
+/**
+ * The line a person reads. `→` is what we asked, `←` what came back, `•` what never left.
+ *
+ * ```text
+ * → chats.history    op 49  seq 3  chat 0
+ * ← chats.history    op 49  seq 3  118ms  4.2 kB  3 messages
+ * • chats.list       offline  cached 42s  25 chats
+ * ```
+ */
+export const renderEvent = (event) => {
+    const parts = [];
+    if (event.event === "cache") {
+        parts.push(event.reason);
+        if (event.ageMs !== undefined)
+            parts.push(`cached ${age(event.ageMs)}`);
+    }
+    else {
+        parts.push(`op ${event.opcode}`, `seq ${event.seq}`);
+    }
+    if (event.ids)
+        for (const [name, value] of Object.entries(event.ids))
+            parts.push(`${name} ${value}`);
+    if (event.event !== "cache") {
+        if (event.durationMs !== undefined)
+            parts.push(`${event.durationMs}ms`);
+        if (event.bytes !== undefined)
+            parts.push(size(event.bytes));
+    }
+    if (event.counts)
+        for (const [field, count] of Object.entries(event.counts))
+            parts.push(`${count} ${field}`);
+    if (event.event !== "cache" && event.errorCode)
+        parts.push(event.errorCode);
+    return `${MARK[event.event]} ${event.operation.padEnd(16)} ${parts.join("  ")}`;
+};
+const MARK = { request: "\u2192", response: "\u2190", cache: "\u2022" };
+const age = (ms) => (ms < 1000 ? `${ms}ms` : `${Math.round(ms / 1000)}s`);
+const size = (bytes) => (bytes < 1000 ? `${bytes} B` : `${(bytes / 1000).toFixed(1)} kB`);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isId = (value) => typeof value === "string" || typeof value === "number" || typeof value === "bigint";
+//# sourceMappingURL=events.js.map

package/dist/runs/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/runs/events.ts"],"names":[],"mappings":"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"}

package/dist/runs/recording.d.ts

@@ -0,0 +1,35 @@
+import { type RenderFormat, type Streams } from "@leemour/cli-core";
+import { type DiagnosticEvent } from "./events.js";
+export interface RecordingOptions {
+    /** As typed, without the arguments: `chats list`. It names the run directory. */
+    command: string;
+    profile: string;
+    /**
+     * What `commander` parsed. `record` is three-valued on purpose: `--record`, `--no-record`, and
+     * absent — the third is where the configuration file's `"record": true` plugs in (thread C).
+     */
+    options: {
+        record?: boolean | undefined;
+        verbose?: boolean | undefined;
+    };
+    /** What `resolveOutput` decided for the data stream. Diagnostics follow it (`NEED-53`). */
+    format: RenderFormat;
+    streams?: Streams;
+    /** Tests point this at a temporary directory. */
+    runsDir?: string;
+    keepDays?: number;
+    now?: () => Date;
+}
+/**
+ * Runs one command with the diagnostics turned on, and **finalizes on every path**.
+ *
+ * Two sinks, one event object (plan §3.1, §3.7): `--verbose` shows it as it happens and keeps
+ * nothing, `--record` keeps it and shows nothing. Either, both, or — by default — neither, in
+ * which case this costs a counter.
+ *
+ * The body gets the emitter to hand to `MaxClient`. 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 that owned it threw on the way out.
+ */
+export declare const recorded: <T>(options: RecordingOptions, body: (events: (event: DiagnosticEvent) => void) => Promise<T>) => Promise<T>;
+//# sourceMappingURL=recording.d.ts.map

package/dist/runs/recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.d.ts","sourceRoot":"","sources":["../../src/runs/recording.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,KAAK,YAAY,EAAE,KAAK,OAAO,EAAE,MAAM,mBAAmB,CAAA;AAE7F,OAAO,EAAE,KAAK,eAAe,EAAe,MAAM,aAAa,CAAA;AAG/D,MAAM,WAAW,gBAAgB;IAC/B,iFAAiF;IACjF,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,OAAO,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;KAAE,CAAA;IACxE,2FAA2F;IAC3F,MAAM,EAAE,YAAY,CAAA;IACpB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAC9B,SAAS,gBAAgB,EACzB,MAAM,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,KAC7D,OAAO,CAAC,CAAC,CAsCX,CAAA"}

package/dist/runs/recording.js

@@ -0,0 +1,53 @@
+import { CliError, processStreams } from "@leemour/cli-core";
+import { VERSION } from "../version.js";
+import { renderEvent } from "./events.js";
+import { runsDirFor, startRun } from "./run.js";
+/**
+ * Runs one command with the diagnostics turned on, and **finalizes on every path**.
+ *
+ * Two sinks, one event object (plan §3.1, §3.7): `--verbose` shows it as it happens and keeps
+ * nothing, `--record` keeps it and shows nothing. Either, both, or — by default — neither, in
+ * which case this costs a counter.
+ *
+ * The body gets the emitter to hand to `MaxClient`. 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 that owned it threw on the way out.
+ */
+export const recorded = async (options, body) => {
+    const streams = options.streams ?? processStreams;
+    const verbose = options.options.verbose === true;
+    const run = options.options.record === true
+        ? startRun({
+            runsDir: options.runsDir ?? runsDirFor(),
+            command: options.command,
+            profile: options.profile,
+            cliVersion: VERSION,
+            ...(options.keepDays === undefined ? {} : { keepDays: options.keepDays }),
+            ...(options.now === undefined ? {} : { now: options.now }),
+        })
+        : undefined;
+    let requests = 0;
+    const events = (event) => {
+        if (event.event === "request")
+            requests += 1;
+        // Text for a person, one JSON object per line for anything else — the rule `resolveOutput`
+        // already applies to the data stream (`NEED-53`). Never stdout, in any mode.
+        if (verbose)
+            streams.diagnostic(options.format === "pretty" ? renderEvent(event) : JSON.stringify(event));
+        run?.logger.info(event);
+    };
+    try {
+        const answer = await body(events);
+        await run?.finish("success", { requests });
+        return answer;
+    }
+    catch (error) {
+        await run?.finish("failed", {
+            requests,
+            // The code a script branches on, never the sentence: MAX's refusals quote our payload back.
+            ...(error instanceof CliError ? { errorCode: error.code } : {}),
+        });
+        throw error;
+    }
+};
+//# sourceMappingURL=recording.js.map

package/dist/runs/recording.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.js","sourceRoot":"","sources":["../../src/runs/recording.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAmC,MAAM,mBAAmB,CAAA;AAC7F,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AACvC,OAAO,EAAwB,WAAW,EAAE,MAAM,aAAa,CAAA;AAC/D,OAAO,EAAY,UAAU,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAoBzD;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,KAAK,EAC3B,OAAyB,EACzB,IAA8D,EAClD,EAAE;IACd,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,cAAc,CAAA;IACjD,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,KAAK,IAAI,CAAA;IAEhD,MAAM,GAAG,GACP,OAAO,CAAC,OAAO,CAAC,MAAM,KAAK,IAAI;QAC7B,CAAC,CAAC,QAAQ,CAAC;YACP,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,UAAU,EAAE;YACxC,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,UAAU,EAAE,OAAO;YACnB,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;YACzE,GAAG,CAAC,OAAO,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;SAC3D,CAAC;QACJ,CAAC,CAAC,SAAS,CAAA;IAEf,IAAI,QAAQ,GAAG,CAAC,CAAA;IAEhB,MAAM,MAAM,GAAG,CAAC,KAAsB,EAAQ,EAAE;QAC9C,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS;YAAE,QAAQ,IAAI,CAAC,CAAA;QAC5C,2FAA2F;QAC3F,6EAA6E;QAC7E,IAAI,OAAO;YAAE,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAA;QACzG,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACzB,CAAC,CAAA;IAED,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,CAAA;QACjC,MAAM,GAAG,EAAE,MAAM,CAAC,SAAS,EAAE,EAAE,QAAQ,EAAE,CAAC,CAAA;QAC1C,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,GAAG,EAAE,MAAM,CAAC,QAAQ,EAAE;YAC1B,QAAQ;YACR,4FAA4F;YAC5F,GAAG,CAAC,KAAK,YAAY,QAAQ,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChE,CAAC,CAAA;QACF,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC,CAAA"}

package/dist/runs/run.d.ts

@@ -0,0 +1,81 @@
+import { type FileLogger } from "@leemour/cli-core";
+export type RunStatus = "success" | "failed";
+/**
+ * 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 MAX's refusals quote the payload back at us.
+ */
+export interface RunMetadata {
+    runId: string;
+    /** As typed, without the arguments: `chats list`, `messages send`. */
+    command: string;
+    profile: string;
+    startedAt: string;
+    completedAt?: string;
+    status: RunStatus | "running";
+    /** How many requests reached MAX. A read the cache answers makes none at all (`MAX-7`). */
+    requests?: number;
+    durationMs?: number;
+    cliVersion: string;
+    errorCode?: string;
+}
+export interface StartRunOptions {
+    runsDir: string;
+    command: string;
+    profile: string;
+    cliVersion: string;
+    /** Older runs are removed as this one starts (`NEED-49`). */
+    keepDays?: number;
+    runId?: string;
+    now?: () => Date;
+}
+export interface Run {
+    id: string;
+    dir: string;
+    logger: FileLogger;
+    /**
+     * Writes the final `run.json` and closes the log. **Must run on every path** — the answer, a
+     * refusal, a failure before the connection was even open. Safe to call twice.
+     */
+    finish(status: RunStatus, extra?: Partial<RunMetadata>): Promise<void>;
+}
+/** 30 days (`NEED-49`). Time is what you think in when asking what you did last week. */
+export declare const KEEP_RUNS_FOR_DAYS = 30;
+/**
+ * `<state dir>/runs`. Beside the profiles and never in the cache directory: a cache is deleted to
+ * fix a cache, and the log is the one thing here that cannot be rebuilt from MAX (`NEED-51`).
+ */
+export declare const runsDirFor: (env?: NodeJS.ProcessEnv) => string;
+/**
+ * Opens a run directory, the shape `braze-cli` arrived at
+ * (`../braze-cli/packages/cli/src/runs/run.ts:74`).
+ *
+ * ```text
+ * <state dir>/runs/2026-09-20/20260920T084431Z-chats-list-a81f2c/
+ *   run.json       what it was, when, which profile, how long, the outcome
+ *   events.jsonl   one JSON object per request, written by Pino, no ANSI ever
+ * ```
+ *
+ * `run.json` is written **now**, with `status: "running"`, and again by `finish`. A directory
+ * holding events and no metadata is a special case `max runs list` would carry forever.
+ */
+export declare const startRun: (options: StartRunOptions) => Run;
+/** Newest first, which is the order anyone asking "what did I just do" wants. */
+export declare const listRuns: (runsDir: string) => RunMetadata[];
+export declare const findRun: (runsDir: string, id: string) => {
+    dir: string;
+    metadata: RunMetadata;
+} | undefined;
+/** The events of one run, in the order they happened. A line that will not parse is skipped. */
+export declare const readEvents: (dir: string) => Record<string, unknown>[];
+/**
+ * Removes every day older than `keepDays`, and answers how many days went.
+ *
+ * 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.
+ */
+export declare const pruneRuns: (runsDir: string, { keepDays, now }: {
+    keepDays: number;
+    now: Date;
+}) => number;
+//# sourceMappingURL=run.d.ts.map

package/dist/runs/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../src/runs/run.ts"],"names":[],"mappings":"AAGA,OAAO,EAAoB,KAAK,UAAU,EAA+B,MAAM,mBAAmB,CAAA;AAElG,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAA;AAE5C;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,MAAM,EAAE,SAAS,GAAG,SAAS,CAAA;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,IAAI,CAAA;CACjB;AAED,MAAM,WAAW,GAAG;IAClB,EAAE,EAAE,MAAM,CAAA;IACV,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,UAAU,CAAA;IAClB;;;OAGG;IACH,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,KAAK,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACvE;AAED,yFAAyF;AACzF,eAAO,MAAM,kBAAkB,KAAK,CAAA;AAEpC;;;GAGG;AACH,eAAO,MAAM,UAAU,GAAI,MAAK,MAAM,CAAC,UAAwB,KAAG,MACY,CAAA;AAE9E;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,QAAQ,GAAI,SAAS,eAAe,KAAG,GAyDnD,CAAA;AAkBD,iFAAiF;AACjF,eAAO,MAAM,QAAQ,GAAI,SAAS,MAAM,KAAG,WAAW,EAUrD,CAAA;AAED,eAAO,MAAM,OAAO,GAAI,SAAS,MAAM,EAAE,IAAI,MAAM,KAAG;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,WAAW,CAAA;CAAE,GAAG,SAO9F,CAAA;AAED,gGAAgG;AAChG,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAoB/D,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,SAAS,GAAI,SAAS,MAAM,EAAE,mBAAmB;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,IAAI,CAAA;CAAE,KAAG,MAc/F,CAAA"}

package/dist/runs/run.js

@@ -0,0 +1,175 @@
+import { randomUUID } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { createFileLogger, resolvePaths, writeSecurely } from "@leemour/cli-core";
+/** 30 days (`NEED-49`). Time is what you think in when asking what you did last week. */
+export const KEEP_RUNS_FOR_DAYS = 30;
+/**
+ * `<state dir>/runs`. Beside the profiles and never in the cache directory: a cache is deleted to
+ * fix a cache, and the log is the one thing here that cannot be rebuilt from MAX (`NEED-51`).
+ */
+export const runsDirFor = (env = process.env) => join(resolvePaths({ appName: "max-cli", prefix: "MAX", env }).state, "runs");
+/**
+ * Opens a run directory, the shape `braze-cli` arrived at
+ * (`../braze-cli/packages/cli/src/runs/run.ts:74`).
+ *
+ * ```text
+ * <state dir>/runs/2026-09-20/20260920T084431Z-chats-list-a81f2c/
+ *   run.json       what it was, when, which profile, how long, the outcome
+ *   events.jsonl   one JSON object per request, written by Pino, no ANSI ever
+ * ```
+ *
+ * `run.json` is written **now**, with `status: "running"`, and again by `finish`. A directory
+ * holding events and no metadata is a special case `max runs list` would carry forever.
+ */
+export const startRun = (options) => {
+    const now = options.now ?? (() => new Date());
+    const startedAt = now();
+    const id = options.runId ?? runId(startedAt, options.command);
+    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 (`NEED-49`).
+    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 logger = createFileLogger({
+        path: events,
+        base: { runId: id, command: options.command, profile: options.profile },
+    });
+    const metadata = {
+        runId: id,
+        command: options.command,
+        profile: options.profile,
+        startedAt: startedAt.toISOString(),
+        status: "running",
+        cliVersion: options.cliVersion,
+    };
+    writeRunFile(dir, metadata);
+    let finished = false;
+    return {
+        id,
+        dir,
+        logger,
+        finish: async (status, extra = {}) => {
+            if (finished)
+                return;
+            finished = true;
+            const completedAt = now();
+            writeRunFile(dir, {
+                ...metadata,
+                ...extra,
+                status,
+                completedAt: completedAt.toISOString(),
+                durationMs: completedAt.getTime() - startedAt.getTime(),
+            });
+            // Pino writes through a plain append stream, and a process that exits before it flushes
+            // loses the tail — which is exactly the run somebody wanted to read.
+            await logger.close();
+        },
+    };
+};
+/** `20260920T084431Z-chats-list-a81f2c` — sortable, and readable without opening it. */
+const runId = (startedAt, command) => {
+    const stamp = startedAt
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\.\d+Z$/, "Z");
+    const slug = command.replace(/[^a-z0-9]+/gi, "-").toLowerCase();
+    return `${stamp}-${slug}-${randomUUID().slice(0, 6)}`;
+};
+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.
+    writeSecurely(join(dir, "run.json"), `${JSON.stringify(metadata, null, 2)}\n`, 0o600);
+};
+/** Newest first, which is the order anyone asking "what did I just do" wants. */
+export const listRuns = (runsDir) => {
+    const runs = [];
+    for (const date of days(runsDir).sort().reverse()) {
+        for (const entry of safeReaddir(join(runsDir, date)).sort().reverse()) {
+            const metadata = readRun(join(runsDir, date, entry));
+            if (metadata)
+                runs.push(metadata);
+        }
+    }
+    return runs;
+};
+export const findRun = (runsDir, id) => {
+    for (const date of days(runsDir)) {
+        const dir = join(runsDir, date, id);
+        const metadata = readRun(dir);
+        if (metadata)
+            return { dir, metadata };
+    }
+    return undefined;
+};
+/** The events of one run, in the order they happened. A line that will not parse is skipped. */
+export const readEvents = (dir) => {
+    let raw;
+    try {
+        raw = readFileSync(join(dir, "events.jsonl"), "utf8");
+    }
+    catch {
+        return [];
+    }
+    const events = [];
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed !== null && typeof parsed === "object")
+                events.push(parsed);
+        }
+        catch {
+            // A half-written last line is what a killed process leaves behind. The rest of the file is
+            // still the run somebody wants to read.
+        }
+    }
+    return events;
+};
+/**
+ * Removes every day older than `keepDays`, and answers how many days went.
+ *
+ * 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.
+ */
+export const pruneRuns = (runsDir, { keepDays, now }) => {
+    const cutoff = day(new Date(now.getTime() - keepDays * 24 * 60 * 60 * 1000));
+    let removed = 0;
+    for (const date of days(runsDir)) {
+        if (date >= cutoff)
+            continue;
+        try {
+            rmSync(join(runsDir, date), { recursive: true, force: true });
+            removed += 1;
+        }
+        catch {
+            // A day we cannot remove is not a reason to fail the command that was only starting.
+        }
+    }
+    return removed;
+};
+const day = (date) => date.toISOString().slice(0, 10);
+const days = (runsDir) => safeReaddir(runsDir).filter((entry) => /^\d{4}-\d{2}-\d{2}$/.test(entry));
+const readRun = (dir) => {
+    try {
+        return JSON.parse(readFileSync(join(dir, "run.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+};
+const safeReaddir = (dir) => {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+};
+//# sourceMappingURL=run.js.map

package/dist/runs/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/runs/run.ts"],"names":[],"mappings":"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"}

package/dist/session/handshake.d.ts

@@ -0,0 +1,26 @@
+import type { Invoke } from "../generated/client.generated.js";
+import type { Payload } from "../protocol/frame.js";
+export interface SessionOptions {
+    token: string;
+    deviceId: string;
+    /** How many chats LOGIN should return with the profile. The specification caps it at 100. */
+    chatsCount?: number;
+}
+/**
+ * INIT then LOGIN, in that order, before anything else will be answered
+ * (`max-api-docs/protocol/auth.md`).
+ *
+ * **Handwritten, and staying that way** (`REQUIREMENTS.md` §9): a socket problem has to be
+ * debuggable without reading a generator. What the specification supplies is the two payloads, so
+ * the field names have one home rather than two.
+ *
+ * It lives here rather than under `protocol/` because it is not transport: the transport moves
+ * frames and does not care who is asking. Establishing a session is this layer's job.
+ *
+ * **It is handed the client's own `invoke` rather than the socket**, so INIT and LOGIN are built,
+ * checked and reported exactly like every other request. They were not, until 2026-09-20: a
+ * diagnostic hook in `MaxClient` saw nothing of the two requests every single invocation makes,
+ * and `max chats list` answers from the LOGIN response without sending anything else.
+ */
+export declare const startSession: (invoke: Invoke, { token, deviceId, chatsCount }: SessionOptions) => Promise<Payload>;
+//# sourceMappingURL=handshake.d.ts.map

package/dist/session/handshake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.d.ts","sourceRoot":"","sources":["../../src/session/handshake.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kCAAkC,CAAA;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAA;AAInD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,6FAA6F;IAC7F,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,MAAM,EACd,iCAAsC,cAAc,KACnD,OAAO,CAAC,OAAO,CAajB,CAAA"}

package/dist/session/handshake.js

@@ -0,0 +1,32 @@
+import { WEB_USER_AGENT } from "../spec/identity.js";
+import { sessionInit, sessionLogin } from "../spec/operations/session.js";
+/**
+ * INIT then LOGIN, in that order, before anything else will be answered
+ * (`max-api-docs/protocol/auth.md`).
+ *
+ * **Handwritten, and staying that way** (`REQUIREMENTS.md` §9): a socket problem has to be
+ * debuggable without reading a generator. What the specification supplies is the two payloads, so
+ * the field names have one home rather than two.
+ *
+ * It lives here rather than under `protocol/` because it is not transport: the transport moves
+ * frames and does not care who is asking. Establishing a session is this layer's job.
+ *
+ * **It is handed the client's own `invoke` rather than the socket**, so INIT and LOGIN are built,
+ * checked and reported exactly like every other request. They were not, until 2026-09-20: a
+ * diagnostic hook in `MaxClient` saw nothing of the two requests every single invocation makes,
+ * and `max chats list` answers from the LOGIN response without sending anything else.
+ */
+export const startSession = async (invoke, { token, deviceId, chatsCount = 40 }) => {
+    await invoke(sessionInit, { userAgent: WEB_USER_AGENT, deviceId });
+    return await invoke(sessionLogin, {
+        token,
+        // A script reading is not a person looking; see the specification for why this is never true.
+        interactive: false,
+        chatsCount,
+        chatsSync: 0,
+        contactsSync: 0,
+        presenceSync: 0,
+        draftsSync: 0,
+    });
+};
+//# sourceMappingURL=handshake.js.map

package/dist/session/handshake.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handshake.js","sourceRoot":"","sources":["../../src/session/handshake.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AACpD,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AASzE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,MAAc,EACd,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,GAAG,EAAE,EAAkB,EAClC,EAAE;IACpB,MAAM,MAAM,CAAC,WAAW,EAAE,EAAE,SAAS,EAAE,cAAc,EAAE,QAAQ,EAAE,CAAC,CAAA;IAElE,OAAO,MAAM,MAAM,CAAC,YAAY,EAAE;QAChC,KAAK;QACL,8FAA8F;QAC9F,WAAW,EAAE,KAAK;QAClB,UAAU;QACV,SAAS,EAAE,CAAC;QACZ,YAAY,EAAE,CAAC;QACf,YAAY,EAAE,CAAC;QACf,UAAU,EAAE,CAAC;KACd,CAAC,CAAA;AACJ,CAAC,CAAA"}

package/dist/session/prompt.d.ts

@@ -0,0 +1,18 @@
+export interface SecretInput {
+    input?: NodeJS.ReadableStream & {
+        isTTY?: boolean;
+    };
+    output?: NodeJS.WritableStream;
+}
+/**
+ * One line of secret, taken without a file and without argv.
+ *
+ * A token on a command line is read by `ps` and kept by shell history; a token in a file is a
+ * second copy nobody remembers to delete. Both are avoided by never letting it land anywhere: it
+ * is typed or piped, goes straight to the keyring, and is never echoed.
+ *
+ * The prompt goes to **stderr**, not stdout, so that `max session start --json` still writes one JSON
+ * value and nothing else.
+ */
+export declare const readSecret: (prompt: string, { input, output }?: SecretInput) => Promise<string>;
+//# sourceMappingURL=prompt.d.ts.map

package/dist/session/prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.d.ts","sourceRoot":"","sources":["../../src/session/prompt.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,GAAG;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;IACnD,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAA;CAC/B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,UAAU,GACrB,QAAQ,MAAM,EACd,oBAAoD,WAAgB,KACnE,OAAO,CAAC,MAAM,CA0BhB,CAAA"}

package/dist/session/prompt.js

@@ -0,0 +1,41 @@
+import { createInterface } from "node:readline";
+import { Writable } from "node:stream";
+/**
+ * One line of secret, taken without a file and without argv.
+ *
+ * A token on a command line is read by `ps` and kept by shell history; a token in a file is a
+ * second copy nobody remembers to delete. Both are avoided by never letting it land anywhere: it
+ * is typed or piped, goes straight to the keyring, and is never echoed.
+ *
+ * The prompt goes to **stderr**, not stdout, so that `max session start --json` still writes one JSON
+ * value and nothing else.
+ */
+export const readSecret = async (prompt, { input = process.stdin, output = process.stderr } = {}) => {
+    if (!input.isTTY) {
+        const chunks = [];
+        for await (const chunk of input)
+            chunks.push(Buffer.from(chunk));
+        return Buffer.concat(chunks).toString("utf8").trim();
+    }
+    let muted = false;
+    const shim = new Writable({
+        write(chunk, _encoding, done) {
+            if (!muted)
+                output.write(chunk);
+            done();
+        },
+    });
+    const reader = createInterface({ input, output: shim, terminal: true });
+    try {
+        const answer = await new Promise((resolve) => {
+            reader.question(prompt, resolve);
+            muted = true;
+        });
+        return answer.trim();
+    }
+    finally {
+        reader.close();
+        output.write("\n");
+    }
+};
+//# sourceMappingURL=prompt.js.map

package/dist/session/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/session/prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAOtC;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,KAAK,EAC7B,MAAc,EACd,EAAE,KAAK,GAAG,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,KAAkB,EAAE,EACnD,EAAE;IACnB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACjB,MAAM,MAAM,GAAa,EAAE,CAAA;QAC3B,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,KAAK;YAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAA;QAChE,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAA;IACtD,CAAC;IAED,IAAI,KAAK,GAAG,KAAK,CAAA;IACjB,MAAM,IAAI,GAAG,IAAI,QAAQ,CAAC;QACxB,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI;YAC1B,IAAI,CAAC,KAAK;gBAAE,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAA;YAC/B,IAAI,EAAE,CAAA;QACR,CAAC;KACF,CAAC,CAAA;IAEF,MAAM,MAAM,GAAG,eAAe,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAA;IACvE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE;YACnD,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;YAChC,KAAK,GAAG,IAAI,CAAA;QACd,CAAC,CAAC,CAAA;QACF,OAAO,MAAM,CAAC,IAAI,EAAE,CAAA;IACtB,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,KAAK,EAAE,CAAA;QACd,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;IACpB,CAAC;AACH,CAAC,CAAA"}

package/dist/session/store.d.ts

@@ -0,0 +1,46 @@
+import { type KeyringStore } from "@leemour/cli-core";
+/**
+ * What a MAX session actually is: a token, and an identity for this installation.
+ *
+ * **The token lives in the OS keyring; the rest lives in a file.** The split is not decoration —
+ * the token is the credential, and the device identity is merely identifying, but it must be
+ * *stable*: a client that presents a new device on every command is not imitating a real client
+ * (REQUIREMENTS §34), and MAX ties sessions to it.
+ */
+export interface SessionState {
+    deviceId: string;
+    /** Set once the account is known; only used to tell our own messages from other people's. */
+    viewerId?: string;
+    /** Counts logins so a token that stops working can be explained rather than guessed at (NEED-8). */
+    logins: number;
+    lastLoginAt?: string;
+}
+export interface SessionStoreOptions {
+    profile?: string;
+    env?: NodeJS.ProcessEnv;
+    keyring?: KeyringStore;
+    /** Overrides the config and state directories; tests pass a temporary one. */
+    configDir?: string;
+    stateDir?: string;
+}
+export declare class SessionStore {
+    #private;
+    readonly profile: string;
+    constructor({ profile, env, keyring, configDir, stateDir }?: SessionStoreOptions);
+    /** `undefined` means nobody has logged in on this profile. */
+    readToken(): string | undefined;
+    writeToken(token: string): void;
+    /**
+     * Reads the state, inventing a device identity the first time and keeping it thereafter.
+     *
+     * **A new identity is written out immediately, before it is used for anything.** Returning one
+     * without saving it looks harmless and is not: a login that fails, or simply a second call,
+     * would then present MAX with a different device every time — which is the "new device on every
+     * command" that §34 exists to prevent. Found by a test, not by a user.
+     */
+    readState(): SessionState;
+    writeState(state: SessionState): void;
+    /** Forgets everything about this profile. Returns whether there was a token to forget. */
+    forget(): boolean;
+}
+//# sourceMappingURL=store.d.ts.map