@cruxy/cli 1.2.0 → 1.3.0

package/dist/render/test-view.js

@@ -0,0 +1,89 @@
+import { fit } from "./layout.js";
+/**
+ * Rendering a test run (P3): the shared formatter behind
+ * {@link StreamRenderer.testResult}, so every medium reports the same run the
+ * same way.
+ *
+ * The honesty rules are `testing/`'s, carried through rather than re-derived:
+ * `passed` comes from the exit code and nothing else, `total` exists only when
+ * a parser confidently extracted it, and `failures` can be empty even for a
+ * failing run. So this NEVER computes a count it was not given — no
+ * `total - failures.length` passed-count, no "1 test failed" inferred from a
+ * non-zero exit. When the numbers are absent it reports the outcome and the
+ * duration, and says that it could not recognize the details.
+ */
+/** Failures listed before the rest are summarized. */
+export const MAX_LISTED_FAILURES = 5;
+/** `4.2s`, `380ms` — a measured duration, never estimated. */
+export function formatDuration(ms) {
+    if (ms < 1000)
+        return `${Math.round(ms)}ms`;
+    const seconds = ms / 1000;
+    return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+}
+/**
+ * The count clause, or "" when nothing countable was extracted.
+ *
+ * `total` is the only number a parser is allowed to produce, and `failures` is
+ * a best-effort list — so "N of M failed" is claimable only when both are
+ * present, and a bare failure list is reported as "N failures" without implying
+ * it is exhaustive.
+ */
+function counts(report, t) {
+    const failed = report.failures.length;
+    if (report.total !== undefined) {
+        if (report.passed)
+            return t.muted(`${report.total} tests`);
+        if (failed > 0)
+            return t.danger(`${failed} of ${report.total} failed`);
+        return t.muted(`${report.total} tests`);
+    }
+    if (!report.passed && failed > 0)
+        return t.danger(`${failed} failure${failed === 1 ? "" : "s"}`);
+    return "";
+}
+/** One failure: its name, then `file:line` when the parser recognized them. */
+function failureLine(failure, t) {
+    const where = failure.file === undefined
+        ? ""
+        : ` ${t.muted(failure.file + (failure.line === undefined ? "" : `:${failure.line}`))}`;
+    return `  ${t.danger(t.glyph.failure)} ${failure.name}${where}`;
+}
+/**
+ * A test run as committed lines: a headline, then the recognized failures.
+ *
+ * This is committed output, not live state — a run is an event that happened,
+ * so every medium keeps it rather than redrawing it.
+ */
+export function testResultLines(report, t, width = Infinity) {
+    const mark = report.passed
+        ? t.success(t.glyph.success)
+        : t.danger(t.glyph.failure);
+    const headline = report.passed
+        ? t.success("tests passed")
+        : t.danger("tests failed");
+    const parts = [
+        counts(report, t),
+        t.muted(formatDuration(report.durationMs)),
+        t.muted(report.command),
+    ].filter((p) => p !== "");
+    const lines = [
+        `${mark} ${headline} ${t.muted(t.glyph.sep)} ${parts.join(t.muted(` ${t.glyph.sep} `))}`,
+    ];
+    for (const failure of report.failures.slice(0, MAX_LISTED_FAILURES))
+        lines.push(failureLine(failure, t));
+    if (report.failures.length > MAX_LISTED_FAILURES) {
+        lines.push(t.muted(`  ${t.glyph.ellipsis} ${report.failures.length - MAX_LISTED_FAILURES} more`));
+    }
+    // Say what is NOT known, rather than letting a bare "tests failed" imply the
+    // details were simply absent from the run.
+    if (!report.passed && report.failures.length === 0) {
+        lines.push(t.muted("  no individual failures were recognized in the output"));
+    }
+    if (report.outputTruncated && report.failures.length > 0) {
+        lines.push(t.muted("  output was capped — the failures above may be incomplete"));
+    }
+    return Number.isFinite(width)
+        ? lines.map((l) => fit(l, width, t.glyph.ellipsis))
+        : lines;
+}

package/dist/render/tty-renderer.js

@@ -5,6 +5,8 @@ import { createStreamHighlighter, } from "./highlight.js";
 import { fit } from "./layout.js";
 import { createFrameClock, inTransition, spinnerGlyph, } from "./motion.js";
 import { ELAPSED_AFTER_MS, fitStatusLine, formatElapsed, phaseIdentity, } from "./state.js";
+import { changedSteps, stepStatusLine } from "./plan-view.js";
+import { testResultLines } from "./test-view.js";
 /** Erase the current line and return the cursor to column 0. */
 const CLEAR_LINE = "\r\x1b[2K";
 /**
@@ -52,6 +54,8 @@ export class TtyRenderer {
     rawStatus = null;
     phase = null;
     progressState = null;
+    /** Last plan snapshot committed, so `setPlan` notes only what changed. */
+    planSteps = [];
     /** When the current phase *identity* began — drives honest elapsed display. */
     phaseStartedAt = 0;
     /** In-flight tool call (serial by contract) for end-note duration. */
@@ -277,6 +281,42 @@ export class TtyRenderer {
         this.progressState = state;
         this.refresh();
     }
+    /**
+     * Commit one trail line per step whose status actually changed (P3). This
+     * medium owns a single live line, which `progress` already uses for the
+     * `[i/n] title` prefix — the checklist itself belongs in committed output,
+     * exactly where the plan executor used to write it through the approval io.
+     *
+     * `note` is the right sink: it hides the live line, writes, and lets the next
+     * transition redraw — so a step line can never land inside the managed row.
+     */
+    setPlan(steps) {
+        if (this.closed)
+            return;
+        if (steps === null) {
+            this.planSteps = [];
+            return;
+        }
+        for (const step of changedSteps(this.planSteps, steps)) {
+            this.note(stepStatusLine(step, this.theme));
+        }
+        this.planSteps = steps.map((s) => ({ ...s }));
+    }
+    /** Committed via `note`, so the live line yields before the block lands. */
+    /**
+     * Ignored: a served tier is standing state, not an event. Committing a line
+     * per request would be noise on an append-only surface, and the run's tier is
+     * already reported by `cruxy usage`.
+     */
+    servedRouting() {
+        // no-op
+    }
+    testResult(report) {
+        if (this.closed)
+            return;
+        for (const line of testResultLines(report, this.theme, this.caps.width))
+            this.note(line);
+    }
     toolLifecycle(event) {
         if (this.closed)
             return;

package/dist/routing/index.js

@@ -1,5 +1,6 @@
 export * from "./types.js";
 export { ConfigRouter, DEFAULT_TIER, routerForConfig, resolveTaskModel, } from "./router.js";
+export { MODEL_CHOICES, SessionModel, describeModelChoice, parseModelChoice, } from "./session-model.js";
 // `resolve.ts` (tier → wire model-id) is deliberately NOT re-exported: the
 // mapping is internal to routing, so it can never be reached from a user-facing
 // render path (the internal-mapping-isolation guarantee, U.8).

package/dist/routing/router.js

@@ -1,6 +1,7 @@
 import { MODEL_TIERS } from "../brand/voice.js";
 import { routingTierUnavailable } from "../errors/index.js";
 import { resolveModelId } from "./resolve.js";
+import { AUTO_MODEL, } from "./types.js";
 /**
  * The tier a config resolves to when nothing else pins one down — mirrors the
  * gateway's `auto` fallback (`AUTO_FALLBACK_TIER` in the SDK), so an unrouted
@@ -73,12 +74,20 @@ export function routerForConfig(config) {
     });
 }
 /**
- * Resolve a declared task class to `{ tier, model }`: the tier for honest
- * surfacing (the U.4 state line), the wire model id for the request. The model
- * id comes from the internal {@link resolveModelId} — callers never touch that
+ * Resolve a declared task class to the wire model for the request, plus the tier
+ * for honest surfacing (the U.4 state line) when there is one. The model id
+ * comes from the internal {@link resolveModelId} — callers never touch that
  * mapping directly, so it stays the single source of truth.
+ *
+ * `tier` is ABSENT exactly when the router declined and the request is going out
+ * as {@link AUTO_MODEL}: no tier has been chosen client-side, so there is
+ * nothing honest to put on the status line until the gateway's opening frame
+ * says what it actually served. Absent is the whole point — a fabricated
+ * "probably vaani" here is precisely the claim `auto` cannot support.
  */
 export function resolveTaskModel(router, taskClass) {
     const tier = router.select(taskClass);
-    return { tier, model: resolveModelId(tier) };
+    return tier === null
+        ? { model: AUTO_MODEL }
+        : { tier, model: resolveModelId(tier) };
 }

package/dist/routing/session-model.js

@@ -0,0 +1,109 @@
+import { MODEL_TIERS } from "../brand/voice.js";
+import { multiplierForTier } from "../usage/weighted.js";
+import { AUTO_MODEL } from "./types.js";
+/**
+ * Everything `/model` offers, in the order it lists them. `auto` leads because
+ * it is the default and because it is the only entry that is not a tier — a
+ * list that buried it among the three would read as a four-tier menu.
+ */
+export const MODEL_CHOICES = [
+    AUTO_MODEL,
+    ...MODEL_TIERS,
+];
+/** Parse a user-typed model name, or `null` — never a guess, never a nearest match. */
+export function parseModelChoice(text) {
+    const want = text.trim().toLowerCase();
+    return MODEL_CHOICES.includes(want)
+        ? want
+        : null;
+}
+/**
+ * One line describing a choice, for the picker and for `/model` with no picker.
+ *
+ * THE ONLY THING SAID ABOUT A TIER IS ITS WEIGHT, and that is deliberate. cruxy
+ * publishes no capability ordering for `kavi`/`vaani`/`mira` — nothing in this
+ * codebase knows which is "smarter" — so a description like "fastest" or "best
+ * for hard problems" would be invented at the exact moment a user is deciding
+ * on it. The weighted multiplier is a real, checkable number this CLI already
+ * meters with (`TIER_MULTIPLIERS`, mirrored from the gateway's budget config),
+ * so it is what the picker says. A tier this build has no multiplier for gets no
+ * claim at all rather than a made-up one.
+ */
+export function describeModelChoice(choice) {
+    if (choice === AUTO_MODEL) {
+        return "the gateway picks a tier per request (not a tier itself)";
+    }
+    const multiplier = multiplierForTier(choice);
+    return multiplier === undefined
+        ? "a routing tier"
+        : `a routing tier · ${multiplier}× weighted`;
+}
+/**
+ * The session's model choice, and the router every part of the session selects
+ * through.
+ */
+export class SessionModel {
+    choice;
+    base;
+    listeners = new Set();
+    /**
+     * @param initial the starting choice — `config.model.model` when it names one
+     *                of {@link MODEL_CHOICES}, else `auto`.
+     * @param base    the config-driven router (`routing.default` / `routing.map`),
+     *                or null when the user configured none. Consulted ONLY while
+     *                the choice is `auto`: a tier picked at runtime is an explicit
+     *                instruction for this session and outranks a config table, the
+     *                same precedence a CLI flag has over a config file.
+     */
+    constructor(initial, base = null) {
+        this.choice = initial;
+        this.base = base;
+    }
+    /** The current choice. The ONE read every surface makes. */
+    current() {
+        return this.choice;
+    }
+    /** Whether a config routing table is in play — so `/model` can say when a pick overrides it. */
+    get hasRoutingTable() {
+        return this.base !== null;
+    }
+    /**
+     * Adopt a new choice. Returns whether anything changed, so a caller can stay
+     * quiet about a no-op rather than announcing a switch that did not happen.
+     * Listeners fire only on a real change.
+     */
+    set(choice) {
+        if (choice === this.choice)
+            return false;
+        this.choice = choice;
+        for (const listener of this.listeners)
+            listener();
+        return true;
+    }
+    /**
+     * Subscribe to changes; returns the unsubscribe. The renderer uses this to
+     * drop the served tier the moment the choice moves — see the note on
+     * `TuiRenderer.attachModel`.
+     */
+    onChange(listener) {
+        this.listeners.add(listener);
+        return () => {
+            this.listeners.delete(listener);
+        };
+    }
+    /**
+     * A pinned tier wins for every task class. `auto` defers to the config table
+     * when there is one (unchanged C.30 behaviour) and otherwise declines, which
+     * sends the request out as `auto` for the gateway to route.
+     *
+     * A pinned tier deliberately flattens the per-task map. The user named one
+     * model for this session; honouring `routing.map` underneath would quietly
+     * send some of their work somewhere else, which is the silent-substitution
+     * failure `ConfigRouter` already refuses to make.
+     */
+    select(taskClass) {
+        if (this.choice !== AUTO_MODEL)
+            return this.choice;
+        return this.base === null ? null : this.base.select(taskClass);
+    }
+}

package/dist/routing/types.js

@@ -25,3 +25,17 @@ export const TASK_CLASSES = [
     /** Context compaction / summarization. */
     "summarize",
 ];
+/**
+ * The server-routing sentinel: a valid `model.model` (and cruxy's default), but
+ * deliberately **not** a {@link Tier} and never a member of `MODEL_TIERS`.
+ *
+ * The distinction is load-bearing rather than pedantic. A tier names one model
+ * for the whole run, fixed before `provider.stream` opens. `auto` names no model
+ * at all — the gateway resolves it PER REQUEST and may downgrade it under budget
+ * pressure, which is why the served tier arrives on the stream's opening frame
+ * and why `auto` can never be reported as "the tier this run used". Anything
+ * that shows a model choice has to say which of the two it is holding; a picker
+ * that listed `auto` alongside the tiers as though it were a fourth one would be
+ * asserting a fixed model where there is none.
+ */
+export const AUTO_MODEL = "auto";

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;
+}