@cruxy/cli 1.2.1 → 1.4.0

package/dist/session/export.js

@@ -0,0 +1,88 @@
+import { COMPACTION_MARKER } from "../agent/prompts.js";
+/**
+ * Rendering a conversation to Markdown for `/export` (P6 track 4).
+ *
+ * WHAT THIS CAN AND CANNOT CONTAIN, said in the file itself rather than left for
+ * someone to discover. The source is `Session.messages` — the LIVE history, the
+ * thing the model can currently see. That is the right source for "export this
+ * conversation", and it is lossy in one specific way: anything a compaction
+ * folded away is present only as the summary that replaced it. The full
+ * transcript survives in the session log, which is append-only precisely so a
+ * compaction never destroys what was said.
+ *
+ * So an export whose history contains a compaction marker says so at the top.
+ * The alternative — exporting silently and letting the reader assume the file is
+ * the whole conversation — is the failure mode worth spending three lines on.
+ *
+ * Tool payloads are included in FULL. An export is a file, not a screen: the
+ * caller asked for the conversation, and a truncated one is a transcript that
+ * cannot be searched for the thing you exported it to find.
+ */
+/** Fence a payload without letting its own backticks break out of the block. */
+function fence(body, lang = "") {
+    // Longest run of backticks in the body, so the fence always outlives it.
+    let longest = 0;
+    for (const match of body.matchAll(/`+/g)) {
+        longest = Math.max(longest, match[0].length);
+    }
+    const ticks = "`".repeat(Math.max(3, longest + 1));
+    return `${ticks}${lang}\n${body}\n${ticks}`;
+}
+/** One content block as Markdown. */
+function renderBlock(block) {
+    switch (block.type) {
+        case "text":
+            return block.text;
+        case "tool_use":
+            return `**called \`${block.name}\`**\n\n${fence(JSON.stringify(block.input, null, 2), "json")}`;
+        case "tool_result":
+            return `**tool result${block.is_error ? " (error)" : ""}**\n\n${fence(block.content)}`;
+    }
+}
+/** One message as a titled Markdown section. */
+function renderMessage(message) {
+    const isUser = message.role === "user";
+    if (typeof message.content === "string") {
+        const compacted = message.content.startsWith(COMPACTION_MARKER);
+        const heading = compacted ? "compaction" : isUser ? "you" : "cruxy";
+        return `## ${heading}\n\n${message.content}`;
+    }
+    // A `role: "user"` message with blocks is a tool RESULT, not something the
+    // human said. Titling it "you" would attribute grep output to the user.
+    const heading = message.content.some((b) => b.type === "tool_result")
+        ? "tools"
+        : isUser
+            ? "you"
+            : "cruxy";
+    return `## ${heading}\n\n${message.content.map(renderBlock).join("\n\n")}`;
+}
+/**
+ * Render a conversation to a Markdown document.
+ *
+ * Pure: no clock, no filesystem, no config. `exportedAt` is passed in for that
+ * reason — a renderer that read the clock could not be tested for its own
+ * output.
+ */
+export function exportMarkdown(messages, meta) {
+    const compacted = messages.some((m) => typeof m.content === "string" && m.content.startsWith(COMPACTION_MARKER));
+    const header = [
+        `# cruxy session ${meta.sessionId.slice(0, 8)}`,
+        "",
+        `- exported: ${meta.exportedAt}`,
+        `- directory: ${meta.cwd}`,
+        `- model: ${meta.provider}${meta.model === undefined ? "" : `/${meta.model}`}`,
+        `- messages: ${messages.length}`,
+    ];
+    if (compacted) {
+        // The one thing a reader could otherwise get wrong about this file.
+        header.push("", "> This conversation was compacted: an earlier stretch of it was replaced by", "> a summary to stay within the context budget, and only that summary appears", "> below. The full transcript is preserved in the session log, which is", "> append-only — `cruxy --resume` lists sessions by id.");
+    }
+    if (messages.length === 0) {
+        return `${[...header, "", "_(no messages)_"].join("\n")}\n`;
+    }
+    return `${[...header, "", ...messages.map(renderMessage)].join("\n\n")}\n`;
+}
+/** The default filename for a session export: `cruxy-session-<short id>.md`. */
+export function defaultExportName(sessionId) {
+    return `cruxy-session-${sessionId.slice(0, 8)}.md`;
+}

package/dist/session/index.js

@@ -0,0 +1,20 @@
+/**
+ * Session persistence (P2): an append-only JSONL event log per conversation,
+ * under `~/.cruxy/projects/<project>/<session-id>.jsonl`.
+ *
+ * The pieces, in the order they matter:
+ *  - `types.ts` — the event shapes, `.passthrough()` throughout so a newer
+ *    cruxy's fields never make an older one discard a session;
+ *  - `log.ts` — the writer: one line per event, `0600`, non-fatal on failure;
+ *  - `replay.ts` — the fold back to state, tolerant of torn/unknown lines;
+ *  - `list.ts` — what the picker and the TUI sidebar both read;
+ *  - `resume.ts` — `--resume <id>` and the bare-`--resume` picker;
+ *  - `paths.ts` — the layout, including the subtrees reserved for P3+.
+ */
+export { PROJECTS_DIR_NAME, RESERVED_SUBDIRS, SESSION_FILE_EXT, projectDir, projectKey, projectsDir, reservedDir, sessionFile, } from "./paths.js";
+export { SessionLog } from "./log.js";
+export { defaultExportName, exportMarkdown, } from "./export.js";
+export { foldEvents, readEvents, readMeta, replaySession } from "./replay.js";
+export { findSession, isAmbiguous, listSessions, summarizeSession, } from "./list.js";
+export { cwdMismatchWarning, describeSession, loadResume, relativeAge, resumeById, resumePicker, shortId, PICKER_LIMIT, } from "./resume.js";
+export { SESSION_FILE_VERSION, SessionEventSchema, SessionMetaSchema, } from "./types.js";

package/dist/session/list.js

@@ -0,0 +1,137 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { projectDir, SESSION_FILE_EXT } from "./paths.js";
+import { MessageSchema, SessionEventSchema, SessionMetaSchema, } from "./types.js";
+/**
+ * Listing sessions for the resume picker and the TUI sidebar (P2). Both read
+ * this one function, so the two surfaces can never disagree about what exists
+ * or in what order.
+ */
+/** How many characters of the first prompt name a session. */
+const TITLE_MAX = 60;
+/** A session with no user turn yet — opened, then abandoned. */
+const UNTITLED = "(no messages)";
+/** First line of `text`, squashed and trimmed to {@link TITLE_MAX}. */
+function toTitle(text) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    if (flat === "")
+        return UNTITLED;
+    return flat.length > TITLE_MAX ? `${flat.slice(0, TITLE_MAX - 1)}…` : flat;
+}
+/**
+ * Summarize one session file: its meta, its first user prompt (the title) and
+ * how many user turns it holds.
+ *
+ * This reads the whole file, which is the honest cost of counting turns. It is
+ * bounded in practice — the picker asks for ten — and a session file is text
+ * measured in tens of kilobytes. If it ever stops being cheap the fix is a
+ * sidecar index, not a partial read that reports a wrong count.
+ */
+export function summarizeSession(file) {
+    let raw;
+    let updatedAt;
+    try {
+        raw = readFileSync(file, "utf8");
+        updatedAt = statSync(file).mtime.toISOString();
+    }
+    catch {
+        return null;
+    }
+    let meta = null;
+    let title = null;
+    let turns = 0;
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        let parsedJson;
+        try {
+            parsedJson = JSON.parse(line);
+        }
+        catch {
+            continue; // torn line — skip, same tolerance as replay
+        }
+        if (meta === null) {
+            const m = SessionMetaSchema.safeParse(parsedJson);
+            if (m.success) {
+                meta = {
+                    sessionId: m.data.sessionId,
+                    file,
+                    startedAt: m.data.startedAt,
+                    updatedAt,
+                    cwd: m.data.cwd,
+                    title: UNTITLED,
+                    turns: 0,
+                };
+                continue;
+            }
+        }
+        const event = SessionEventSchema.safeParse(parsedJson);
+        if (!event.success || event.data.kind !== "append")
+            continue;
+        for (const message of event.data.messages) {
+            const parsed = MessageSchema.safeParse(message);
+            if (!parsed.success)
+                continue;
+            // A user turn is a `role: "user"` message with STRING content. Tool
+            // results are also role "user" but carry blocks, so this counts what the
+            // human actually said and nothing else — the same shape test
+            // `Session.findCut` uses to find a real turn boundary.
+            if (parsed.data.role !== "user" ||
+                typeof parsed.data.content !== "string")
+                continue;
+            turns++;
+            if (title === null)
+                title = toTitle(parsed.data.content);
+        }
+    }
+    if (meta === null)
+        return null;
+    return { ...meta, title: title ?? UNTITLED, turns };
+}
+/**
+ * Every session recorded for `cwd`'s project, most-recently-updated first.
+ * Missing directory → empty list (not an error: no sessions yet is normal).
+ */
+export function listSessions(cwd, limit = Infinity) {
+    const dir = projectDir(cwd);
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const summaries = [];
+    for (const name of names) {
+        if (!name.endsWith(SESSION_FILE_EXT))
+            continue;
+        const summary = summarizeSession(path.join(dir, name));
+        if (summary)
+            summaries.push(summary);
+    }
+    summaries.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    return Number.isFinite(limit) ? summaries.slice(0, limit) : summaries;
+}
+/**
+ * Find one session by id (or unambiguous id prefix) within `cwd`'s project.
+ * Returns null when nothing matches; throws nothing — the caller decides how
+ * loudly to fail.
+ *
+ * Prefix matching exists because the ids are UUIDs and nobody is going to type
+ * one; the picker and the sidebar both show a short form.
+ */
+export function findSession(cwd, id) {
+    const all = listSessions(cwd);
+    const exact = all.find((s) => s.sessionId === id);
+    if (exact)
+        return exact;
+    const matches = all.filter((s) => s.sessionId.startsWith(id));
+    return matches.length === 1 ? matches[0] : null;
+}
+/** Whether an id prefix matches more than one session (an ambiguous resume). */
+export function isAmbiguous(cwd, id) {
+    const all = listSessions(cwd);
+    if (all.some((s) => s.sessionId === id))
+        return false;
+    return all.filter((s) => s.sessionId.startsWith(id)).length > 1;
+}

package/dist/session/log.js

@@ -0,0 +1,137 @@
+import { appendFileSync, mkdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { APP_VERSION } from "../constants.js";
+import { sessionFile } from "./paths.js";
+import { SESSION_FILE_VERSION, } from "./types.js";
+export class SessionLog {
+    file;
+    logger;
+    currentRunId;
+    /** Set once a write fails: the log goes inert rather than warning per turn. */
+    broken = false;
+    constructor(file, opts) {
+        this.file = file;
+        this.logger = opts.logger;
+        this.currentRunId = opts.currentRunId;
+    }
+    /**
+     * Open (or create) a session log. A NEW file gets its `meta` line; reopening
+     * an existing one (a `--resume`) does not — `meta` describes where and when
+     * the conversation began, and a second copy written from wherever it was
+     * resumed would make "the session's directory" ambiguous. Replay already
+     * takes the first `meta`, so a duplicate could only ever mislead a later
+     * reader, never help one.
+     *
+     * Returns `null` when a new log cannot be created at all — the caller then
+     * runs without persistence rather than failing, exactly as a corrupt usage
+     * store is survivable. A reopen never returns null: a write problem on an
+     * existing file surfaces on the first append, which warns and goes inert.
+     */
+    static open(opts) {
+        const file = opts.file ?? sessionFile(opts.cwd, opts.sessionId);
+        const log = new SessionLog(file, opts);
+        if (hasContent(file))
+            return log;
+        const ok = log.write({
+            kind: "meta",
+            version: SESSION_FILE_VERSION,
+            sessionId: opts.sessionId,
+            startedAt: new Date().toISOString(),
+            cwd: opts.cwd,
+            roots: opts.roots ?? [],
+            cliVersion: APP_VERSION,
+            ...(opts.provider !== undefined ? { provider: opts.provider } : {}),
+            ...(opts.model !== undefined ? { model: opts.model } : {}),
+        });
+        return ok ? log : null;
+    }
+    /** Messages appended to the history since the last event. */
+    append(messages) {
+        if (messages.length === 0)
+            return;
+        this.write({
+            kind: "append",
+            at: new Date().toISOString(),
+            ...this.runId(),
+            messages,
+        });
+    }
+    /** An older prefix of `replaced` messages was folded into `summary`. */
+    compaction(replaced, summary) {
+        this.write({
+            kind: "compaction",
+            at: new Date().toISOString(),
+            ...this.runId(),
+            replaced,
+            summary,
+        });
+    }
+    /** `/clear` — history dropped, session kept. */
+    clear() {
+        this.write({ kind: "clear", at: new Date().toISOString() });
+    }
+    /**
+     * The session mode changed (P5 track 3). Replaces the `plan-mode` event,
+     * which is still READ for sessions recorded before modes existed but is no
+     * longer written.
+     */
+    mode(mode) {
+        this.write({ kind: "mode", at: new Date().toISOString(), mode });
+    }
+    /**
+     * One turn's token usage. Copied here rather than referenced, because the
+     * usage store keeps only its newest 50 runs while sessions are kept
+     * indefinitely — see the note on `UsageEventSchema`.
+     */
+    usage(inputTokens, outputTokens) {
+        this.write({
+            kind: "usage",
+            at: new Date().toISOString(),
+            ...this.runId(),
+            inputTokens,
+            outputTokens,
+        });
+    }
+    runId() {
+        const id = this.currentRunId?.();
+        return id === undefined ? {} : { runId: id };
+    }
+    /**
+     * Append one event as a single line. Returns whether it landed. The first
+     * failure warns and latches `broken`, so a persistent problem (a full disk)
+     * produces one diagnostic rather than one per turn.
+     */
+    write(event) {
+        if (this.broken)
+            return false;
+        try {
+            mkdirSync(path.dirname(this.file), { recursive: true });
+            // `mode` applies only when the file is created — 0600 from the first
+            // line, matching credentials/usage/memory.
+            appendFileSync(this.file, `${JSON.stringify(event)}\n`, { mode: 0o600 });
+            return true;
+        }
+        catch (err) {
+            this.broken = true;
+            this.logger?.warn(`session not being saved: ${err.message} (the conversation continues in memory)`);
+            return false;
+        }
+    }
+}
+/**
+ * Whether `file` is an existing log with content — i.e. this is a reopen.
+ *
+ * `isFile()` matters: a DIRECTORY at this path reports a non-zero size, so a
+ * size check alone would read an unwritable path as a healthy existing log,
+ * skip the meta write, and hand back a recorder that silently fails on its
+ * first append instead of declining up front.
+ */
+function hasContent(file) {
+    try {
+        const stat = statSync(file);
+        return stat.isFile() && stat.size > 0;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/session/paths.js

@@ -0,0 +1,73 @@
+import path from "node:path";
+import { globalDir } from "../config/paths.js";
+/**
+ * Where sessions live on disk (P2).
+ *
+ * ```
+ * ~/.cruxy/projects/<project>/
+ *   <session-id>.jsonl        ← the event log (P2)
+ *   subagents/                ← reserved, P3+
+ *   tool-results/             ← reserved, P3+
+ *   file-history/             ← reserved, P3+
+ *   memory/                   ← reserved, P3+
+ * ```
+ *
+ * Everything resolves through {@link globalDir}, never a fresh `homedir()` —
+ * one accessor owns the location of `~/.cruxy` and the tests can point it
+ * somewhere else by pointing that.
+ *
+ * The reserved subdirectories are DECLARED here and not created: an empty
+ * directory tree is noise until something writes to it, but naming the paths
+ * now is what stops P3 from inventing a second, conflicting layout.
+ */
+/** `~/.cruxy/projects` */
+export const PROJECTS_DIR_NAME = "projects";
+/** Session event-log extension. */
+export const SESSION_FILE_EXT = ".jsonl";
+/** Reserved subtrees — declared for P3+, deliberately not created by P2. */
+export const RESERVED_SUBDIRS = [
+    "subagents",
+    "tool-results",
+    "file-history",
+    "memory",
+];
+/**
+ * The directory key for a working directory: every run of non-alphanumerics
+ * collapses to a single `-`, with leading/trailing separators trimmed.
+ *
+ * Flattening the path rather than nesting it keeps one directory per project
+ * (so listing is a single readdir) and cannot escape the projects root the way
+ * a path fragment could. It is deliberately NOT reversible — the true `cwd` is
+ * recorded in each session's `meta` event, which is what resume validates
+ * against; the key is only an index.
+ *
+ * Two different directories CAN collide onto one key (`/a/b` and `/a-b`). That
+ * is why resume compares `meta.cwd`, not the key, before trusting a session.
+ */
+export function projectKey(cwd) {
+    const key = path.resolve(cwd).replace(/[^a-zA-Z0-9]+/g, "-");
+    const trimmed = key.replace(/^-+/, "").replace(/-+$/, "");
+    // A path of nothing but separators (`/`) collapses to empty; give it a name
+    // rather than writing into the projects root itself.
+    return trimmed === "" ? "root" : trimmed;
+}
+/** `~/.cruxy/projects` */
+export function projectsDir() {
+    return path.join(globalDir(), PROJECTS_DIR_NAME);
+}
+/**
+ * `~/.cruxy/projects/<project>` for a working directory. Multi-root sessions
+ * pass the PRIMARY root — the session belongs to one project even when it can
+ * read several, and `meta.roots` is what records the rest.
+ */
+export function projectDir(cwd) {
+    return path.join(projectsDir(), projectKey(cwd));
+}
+/** `~/.cruxy/projects/<project>/<session-id>.jsonl` */
+export function sessionFile(cwd, sessionId) {
+    return path.join(projectDir(cwd), `${sessionId}${SESSION_FILE_EXT}`);
+}
+/** A reserved subtree's path (P3+). Declared, not created. */
+export function reservedDir(cwd, name) {
+    return path.join(projectDir(cwd), name);
+}

package/dist/session/replay.js

@@ -0,0 +1,169 @@
+import { readFileSync } from "node:fs";
+import { modeFromFlags } from "../agent/mode.js";
+import { SessionEventSchema, SessionMetaSchema, } from "./types.js";
+/**
+ * Replay: fold an append-only event log back into the state a session needs to
+ * resume (P2).
+ *
+ * The fold is total and order-dependent — `append` grows the array,
+ * `compaction` replaces its head, `clear` empties it — so the result is exactly
+ * the array the model last saw, including the synthetic compaction summaries.
+ * Nothing is re-derived or re-summarised on the way back in.
+ *
+ * TOLERANCE IS THE POINT. A line that will not parse is SKIPPED and counted,
+ * never fatal:
+ *  - a torn final line from a crash mid-append would otherwise cost the whole
+ *    conversation (this is the failure temp-then-rename buys off at write time;
+ *    an append-only log buys it off here instead);
+ *  - a line from a NEWER cruxy carrying an event kind this build has never
+ *    heard of is skipped rather than rejected, which together with the
+ *    `.passthrough()` schemas is what keeps two CLI versions able to share one
+ *    home directory.
+ * `SessionState.skipped` carries the count so a caller can say so out loud
+ * rather than presenting a partial history as complete.
+ */
+/**
+ * The one cast in this module, isolated and explained.
+ *
+ * `MessageSchema` is `.passthrough()`, so its inferred type carries an index
+ * signature that the SDK's `Message` interface does not declare. The values are
+ * structurally identical — the schema validates every field `Message` requires
+ * and preserves the rest — so this narrows a validated value to the nominal
+ * type the rest of the CLI speaks. It is sound precisely BECAUSE the schema ran
+ * first; do not move it above the parse.
+ */
+function asMessages(validated) {
+    return validated;
+}
+/** Parse one line, or `null` when it is unusable (torn, or an unknown kind). */
+function parseLine(line) {
+    const trimmed = line.trim();
+    if (trimmed === "")
+        return null;
+    let raw;
+    try {
+        raw = JSON.parse(trimmed);
+    }
+    catch {
+        return null;
+    }
+    const parsed = SessionEventSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+}
+/**
+ * Fold events into {@link SessionState}. Exported separately from file reading
+ * so the fold is directly testable without a filesystem — the same split as
+ * `render/state.ts` (pure) versus the renderers.
+ *
+ * Throws only when there is no usable `meta` line: without it we do not know
+ * which directory the history refers to, and resuming a conversation whose
+ * origin is unknown is precisely what ruling 4 forbids.
+ */
+export function foldEvents(events, skipped = 0) {
+    const metaEvent = events.find((e) => e.kind === "meta");
+    if (!metaEvent) {
+        throw new Error("session log has no readable meta line");
+    }
+    const meta = metaEvent;
+    let messages = [];
+    // Both are folded, and `mode` wins when present. A journal written before P5
+    // has only `plan-mode` events; one written after has only `mode` events; a
+    // session resumed by a P5 build and then continued has both, in that order.
+    // Last-writer-wins across the two would be wrong — the pre-P5 events are all
+    // earlier, so the newer vocabulary must take precedence rather than the newer
+    // timestamp.
+    let planMode = false;
+    let mode = null;
+    const usage = { input_tokens: 0, output_tokens: 0 };
+    for (const event of events) {
+        switch (event.kind) {
+            case "append":
+                messages = [...messages, ...asMessages(event.messages)];
+                break;
+            case "compaction":
+                // Exactly what `Session.runCompaction` did in memory: drop the head,
+                // splice the synthetic pair in front of what was kept.
+                messages = [
+                    ...asMessages(event.summary),
+                    ...messages.slice(event.replaced),
+                ];
+                break;
+            case "clear":
+                messages = [];
+                break;
+            case "plan-mode":
+                planMode = event.enabled;
+                break;
+            case "mode":
+                mode = event.mode;
+                break;
+            case "usage":
+                usage.input_tokens += event.inputTokens;
+                usage.output_tokens += event.outputTokens;
+                break;
+            case "meta":
+                break;
+        }
+    }
+    return {
+        meta,
+        messages,
+        usage,
+        // A pre-P5 journal's plan flag becomes the mode it was equivalent to.
+        // Auto-approve reads false there, which is right: it was not a thing that
+        // could be on, so nothing is being inferred.
+        mode: mode ?? modeFromFlags(planMode, false),
+        skipped,
+    };
+}
+/** Read and parse a session file into its events, counting unusable lines. */
+export function readEvents(file) {
+    const raw = readFileSync(file, "utf8");
+    const events = [];
+    let skipped = 0;
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        const event = parseLine(line);
+        if (event)
+            events.push(event);
+        else
+            skipped++;
+    }
+    return { events, skipped };
+}
+/** Read a session file and fold it into resumable state. */
+export function replaySession(file) {
+    const { events, skipped } = readEvents(file);
+    return foldEvents(events, skipped);
+}
+/**
+ * Read ONLY the meta line — enough to list a session without folding its whole
+ * history. Returns null when the file has no usable meta.
+ */
+export function readMeta(file) {
+    let raw;
+    try {
+        raw = readFileSync(file, "utf8");
+    }
+    catch {
+        return null;
+    }
+    for (const line of raw.split("\n")) {
+        if (line.trim() === "")
+            continue;
+        try {
+            const parsed = SessionMetaSchema.safeParse(JSON.parse(line));
+            if (parsed.success)
+                return parsed.data;
+        }
+        catch {
+            // keep scanning: a torn first line must not hide a good meta below it
+        }
+        // Only the meta line is expected first; if the first usable line is some
+        // other event the file is malformed for our purposes, but keep scanning
+        // rather than giving up — the cost is bounded and the payoff is a session
+        // that lists instead of vanishing.
+    }
+    return null;
+}