@cruxy/cli 1.2.1 → 1.4.0

package/dist/session/resume.js

@@ -0,0 +1,128 @@
+import { selectList } from "../components/index.js";
+import { usageError } from "../errors/index.js";
+import { findSession, isAmbiguous, listSessions } from "./list.js";
+import { replaySession } from "./replay.js";
+/** How many sessions the bare-`--resume` picker offers. */
+export const PICKER_LIMIT = 10;
+/** Short, stable id form — enough to identify a session, short enough to type. */
+export function shortId(sessionId) {
+    return sessionId.slice(0, 8);
+}
+/** `2h ago`, `3d ago` — relative age for the picker and the sidebar. */
+export function relativeAge(iso, now = Date.now()) {
+    const then = Date.parse(iso);
+    if (Number.isNaN(then))
+        return "unknown";
+    const seconds = Math.max(0, Math.floor((now - then) / 1000));
+    if (seconds < 60)
+        return "just now";
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    return `${Math.floor(hours / 24)}d ago`;
+}
+/** One picker/sidebar row: `3f2a1b0c  2h ago  fix the failing test  (4 turns)`. */
+export function describeSession(s, now = Date.now()) {
+    const turns = `${s.turns} turn${s.turns === 1 ? "" : "s"}`;
+    return `${shortId(s.sessionId)}  ${relativeAge(s.updatedAt, now)}  ${s.title}  (${turns})`;
+}
+/**
+ * Compare the session's recorded directory with the one we are resuming into.
+ * Returns a warning to print, or null when they agree.
+ *
+ * This is ruling 4's "warn loudly, never silently mismatch". The history is
+ * full of file paths, diffs and tool results that only mean anything relative
+ * to the directory they were produced in; replaying it somewhere else does not
+ * corrupt anything, but it does mean the model is reasoning about a tree that
+ * is not the one in front of it. So the resume PROCEEDS — the user asked for
+ * it, and refusing a resume because a repo moved would be worse — but it says
+ * exactly what is off.
+ */
+export function cwdMismatchWarning(state, cwd) {
+    if (state.meta.cwd === cwd)
+        return null;
+    return (`this session was recorded in ${state.meta.cwd}, but you are in ${cwd} — ` +
+        `its history refers to files and paths from the original directory`);
+}
+/**
+ * Load one session and collect its warnings. Throws a usage error when the
+ * file cannot be replayed at all (no meta line) — an unreadable session is
+ * worth failing loudly on, unlike an individual torn line.
+ */
+export function loadResume(session, cwd) {
+    let state;
+    try {
+        state = replaySession(session.file);
+    }
+    catch (err) {
+        throw usageError(`could not resume session ${shortId(session.sessionId)}`, [
+            `the log at ${session.file} is not readable: ${err.message}`,
+            "start a new session with `cruxy`",
+        ]);
+    }
+    const warnings = [];
+    const mismatch = cwdMismatchWarning(state, cwd);
+    if (mismatch)
+        warnings.push(mismatch);
+    if (state.skipped > 0) {
+        warnings.push(`${state.skipped} unreadable line${state.skipped === 1 ? "" : "s"} in the session log were skipped — ` +
+            `the restored history may be incomplete`);
+    }
+    return { session, state, warnings };
+}
+/**
+ * Resolve `--resume <id>`. Fails loud on an unknown or ambiguous id rather than
+ * silently starting a new session — the user named something specific.
+ */
+export function resumeById(cwd, id) {
+    if (isAmbiguous(cwd, id)) {
+        const matches = listSessions(cwd)
+            .filter((s) => s.sessionId.startsWith(id))
+            .map((s) => shortId(s.sessionId));
+        throw usageError(`\`${id}\` matches more than one session`, [
+            `did you mean one of: ${matches.join(", ")}?`,
+            "run `cruxy --resume` to pick from a list",
+        ]);
+    }
+    const found = findSession(cwd, id);
+    if (!found) {
+        throw usageError(`no session \`${id}\` in this project`, [
+            "run `cruxy --resume` to pick from recent sessions",
+            "sessions are per-directory; check you are in the right one",
+        ]);
+    }
+    return loadResume(found, cwd);
+}
+/**
+ * Bare `--resume`: pick from the most recent sessions, or start a new one.
+ * Returns null when the user chose "new session" (or cancelled) — the caller
+ * then proceeds exactly as an unresumed run.
+ */
+export async function resumePicker(cwd, opts = {}) {
+    const sessions = listSessions(cwd, PICKER_LIMIT);
+    if (sessions.length === 0) {
+        opts.logger?.info("no saved sessions for this project — starting a new one");
+        return null;
+    }
+    const now = opts.now ?? Date.now();
+    const rows = [
+        ...sessions.map((session) => ({ kind: "session", session })),
+        { kind: "new" },
+    ];
+    const picked = await selectList(rows, {
+        title: "resume a session",
+        toLabel: (row) => row.kind === "new"
+            ? "+ new session"
+            : describeSession(row.session, now),
+        // Non-interactive with no id named: starting fresh is the safe default,
+        // never an arbitrary session picked on the user's behalf.
+        defaultValue: { kind: "new" },
+        nonInteractiveHint: ["pass an id: `cruxy --resume <id>`"],
+    }, opts.io);
+    if (picked.kind === "cancelled" || picked.value.kind === "new")
+        return null;
+    return loadResume(picked.value.session, cwd);
+}

package/dist/session/types.js

@@ -0,0 +1,223 @@
+import { z } from "zod";
+/**
+ * Session persistence (P2): the on-disk shape of a conversation.
+ *
+ * The file is an APPEND-ONLY event log (JSONL), not a snapshot of the message
+ * array. That distinction is the whole design:
+ *
+ * - `Session.messages` is rewritten in place — compaction replaces an older
+ *   prefix with a synthetic summary pair (see `agent/session.ts`). A snapshot
+ *   format would have to rewrite the whole file on every turn, which is O(n²)
+ *   in turns and loses the history of what was compacted away.
+ * - An event log records the rewrite as an EVENT (`compaction`, carrying what
+ *   it replaced), so the file only ever grows, and replay reconstructs the
+ *   current array exactly. What the model can still see and what the user
+ *   actually said stay separately recoverable.
+ *
+ * Replay is a fold over the events; see `replay.ts`.
+ */
+/**
+ * Bump when the event shapes change incompatibly. Present on the `meta` line
+ * only — every subsequent line is self-describing via `kind`.
+ */
+export const SESSION_FILE_VERSION = 1;
+/**
+ * FORWARD COMPATIBILITY — why every schema below is `.passthrough()`.
+ *
+ * This is the same decision, for the same recorded reason, as
+ * `usage/types.ts`: a `.strict()` schema means the first field a NEWER cruxy
+ * writes makes an OLDER binary reject the line. For usage that silently lost
+ * accounting; here it would silently lose a user's CONVERSATION, which is
+ * strictly worse. Downgrading a CLI, or running two versions against one home
+ * directory, is ordinary — losing a session to it is not acceptable.
+ *
+ * `.passthrough()` also PRESERVES unknown keys rather than stripping them, so
+ * anything that reads and re-emits an event hands a newer CLI's fields back
+ * intact.
+ *
+ * The tradeoff accepted, identically: a typo'd key is no longer a parse error.
+ * Worth it — every field the code actually reads is still fully validated, and
+ * a malformed LINE is skipped rather than taking the session down (see
+ * `replay.ts`).
+ */
+// ── message shapes (mirrors @cruxy/sdk, validated on the way back in) ────────
+/**
+ * The SDK's content blocks, restated as schemas.
+ *
+ * These must round-trip EXACTLY. `tool_use` / `tool_result` pairing is
+ * load-bearing: the provider rejects a history where a `tool_use` has no
+ * matching `tool_result`, which is the entire reason `Session.findCut` walks
+ * back to a real user prompt before compacting. A replay that dropped, merged
+ * or reordered a block would produce a history that fails on the next turn —
+ * so nothing here is lossy, and unknown block types are preserved rather than
+ * filtered (a newer CLI's block must survive an older one reading the file).
+ */
+export const TextBlockSchema = z
+    .object({ type: z.literal("text"), text: z.string() })
+    .passthrough();
+export const ToolUseBlockSchema = z
+    .object({
+    type: z.literal("tool_use"),
+    id: z.string(),
+    name: z.string(),
+    input: z.unknown(),
+})
+    .passthrough();
+export const ToolResultBlockSchema = z
+    .object({
+    type: z.literal("tool_result"),
+    tool_use_id: z.string(),
+    content: z.string(),
+    is_error: z.boolean().optional(),
+})
+    .passthrough();
+/**
+ * A block of a kind this build knows, OR any other object carrying a string
+ * `type`. The fallback arm is deliberate: a newer cruxy that adds a block kind
+ * must not have its sessions truncated by an older one. The block is carried
+ * through untouched and handed back to the provider as-is.
+ */
+export const ContentBlockSchema = z.union([
+    TextBlockSchema,
+    ToolUseBlockSchema,
+    ToolResultBlockSchema,
+    z.object({ type: z.string() }).passthrough(),
+]);
+export const MessageSchema = z
+    .object({
+    role: z.enum(["user", "assistant"]),
+    content: z.union([z.string(), z.array(ContentBlockSchema)]),
+})
+    .passthrough();
+// ── events ───────────────────────────────────────────────────────────────────
+/** One declared workspace root, recorded so a resume can validate against it. */
+export const RootRefSchema = z
+    .object({ name: z.string(), path: z.string() })
+    .passthrough();
+/**
+ * The first line of every session file: everything needed to identify the
+ * session and to decide whether resuming it HERE is safe.
+ *
+ * `cwd` and `roots` are metadata, never restored. Resuming a session recorded
+ * in another directory would silently point a history full of file paths, diffs
+ * and tool results at an unrelated tree — so the resume path compares and warns
+ * loudly rather than quietly proceeding (see `replay.ts`/`resume.ts`).
+ */
+export const SessionMetaSchema = z
+    .object({
+    kind: z.literal("meta"),
+    version: z.literal(SESSION_FILE_VERSION),
+    sessionId: z.string(),
+    startedAt: z.string(),
+    /** The primary root at session start — the directory history refers to. */
+    cwd: z.string(),
+    /** Every declared root (C.26). Multi-root sessions key on the primary, so
+     * this is what makes the asymmetry visible rather than silently dropped. */
+    roots: z.array(RootRefSchema).default([]),
+    cliVersion: z.string().optional(),
+    provider: z.string().optional(),
+    model: z.string().optional(),
+})
+    .passthrough();
+/**
+ * Messages appended since the last event. The ONLY growth path — every turn's
+ * user prompt, assistant blocks and tool results arrive through here.
+ *
+ * `runId` is the CheckpointGate's run id for the turn (see `gate.ts`), NOT a
+ * second id minted here: `cruxy rollback <id>` and this log must agree on what
+ * a turn is, or the undo unit means two different things. It is absent when
+ * checkpoints are disabled — the only case where no run id exists at all.
+ */
+export const AppendEventSchema = z
+    .object({
+    kind: z.literal("append"),
+    at: z.string(),
+    runId: z.string().optional(),
+    messages: z.array(MessageSchema),
+})
+    .passthrough();
+/**
+ * A compaction: the oldest `replaced` messages were folded into `summary`
+ * (the synthetic user/assistant pair carrying `COMPACTION_MARKER`).
+ *
+ * Recording the COUNT plus the replacement — rather than rewriting the array —
+ * is what keeps the file append-only. The replaced messages remain earlier in
+ * the log, so the full conversation is still recoverable even though the model
+ * can no longer see it.
+ */
+export const CompactionEventSchema = z
+    .object({
+    kind: z.literal("compaction"),
+    at: z.string(),
+    runId: z.string().optional(),
+    /** How many messages from the head were folded away. */
+    replaced: z.number().int().nonnegative(),
+    /** What replaced them (the synthetic pair). */
+    summary: z.array(MessageSchema),
+})
+    .passthrough();
+/** `/clear`: history dropped, session kept. Replay resets to an empty array. */
+export const ClearEventSchema = z
+    .object({ kind: z.literal("clear"), at: z.string() })
+    .passthrough();
+/**
+ * `/plan` toggled. The last one wins on replay.
+ *
+ * Superseded by {@link SessionModeEventSchema} (P5 track 3) and still READ, never
+ * written: sessions recorded before modes existed carry these, and dropping the
+ * case would silently resume them in manual. Expand-contract — the new writer
+ * emits `mode`, the reader understands both, and a pre-P5 log keeps meaning what
+ * it meant.
+ */
+export const PlanModeEventSchema = z
+    .object({
+    kind: z.literal("plan-mode"),
+    at: z.string(),
+    enabled: z.boolean(),
+})
+    .passthrough();
+/**
+ * The session mode changed (P5 track 3). The last one wins on replay, exactly
+ * like the event it replaces.
+ *
+ * `mode` is a plain string here rather than an enum so an unknown value — a log
+ * written by a newer build that added a mode — parses instead of poisoning the
+ * whole line. The fold decides what to do with one it does not recognise.
+ */
+export const SessionModeEventSchema = z
+    .object({
+    kind: z.literal("mode"),
+    at: z.string(),
+    mode: z.string(),
+})
+    .passthrough();
+/**
+ * One turn's token usage, as the provider reported it. Summed on replay to
+ * restore `Session.usage`.
+ *
+ * This is a COPY, deliberately. `~/.cruxy/usage/runs.json` keeps only the last
+ * 50 runs (`usage/store.ts`), while sessions are kept indefinitely — so a
+ * session will routinely outlive its own usage records. Without this the
+ * restored `Session.usage` would silently read 0 for an older conversation.
+ * `runId` still points at the usage store for the richer per-tier/cost
+ * breakdown WHEN it is still there; nothing here assumes it is.
+ */
+export const UsageEventSchema = z
+    .object({
+    kind: z.literal("usage"),
+    at: z.string(),
+    runId: z.string().optional(),
+    inputTokens: z.number().int().nonnegative(),
+    outputTokens: z.number().int().nonnegative(),
+})
+    .passthrough();
+/** Every event, discriminated on `kind`. */
+export const SessionEventSchema = z.discriminatedUnion("kind", [
+    SessionMetaSchema,
+    AppendEventSchema,
+    CompactionEventSchema,
+    ClearEventSchema,
+    PlanModeEventSchema,
+    SessionModeEventSchema,
+    UsageEventSchema,
+]);

package/dist/subagent/orchestrator.js

@@ -437,6 +437,29 @@ class SubagentRenderer {
     }
     /** The plan executor owns the progress register (C.31) — never the child. */
     progress() { }
+    /**
+     * Same ownership rule for the plan checklist (P3): a child running its own
+     * task must never overwrite the parent's plan on screen.
+     */
+    setPlan() { }
+    /**
+     * Forwarded: a child's test run is a real outcome the user should see, unlike
+     * its assistant text. The label is not prefixed — the report carries the
+     * command it ran, which already identifies it.
+     */
+    /**
+     * NOT forwarded, deliberately. A subagent may run on a different tier from
+     * the main loop (C.30 routes by task class), and the parent's model panel and
+     * header describe the SESSION's tier. Forwarding would let a subagent's tier
+     * overwrite it and linger after the subagent finished — the header would
+     * report a tier the conversation is not running on.
+     */
+    servedRouting() {
+        // no-op
+    }
+    testResult(report) {
+        this.inner.testResult(report);
+    }
     toolLifecycle(event) {
         this.inner.toolLifecycle({
             ...event,

package/dist/testing/run-tests-tool.js

@@ -144,6 +144,14 @@ export function makeRunTestsTool(deps = {}) {
                 shell: ctx.config.shell,
             });
             budget.record(result.passed);
+            // The structured result goes to the renderer here, from the same object
+            // the payload below is built from — never from re-reading that payload.
+            try {
+                deps.onResult?.(result, resolved);
+            }
+            catch {
+                // A renderer problem is not a test-run problem.
+            }
             const payload = renderResult(result, resolved, {
                 run: result.passed ? 0 : budget.spent,
                 max,

package/dist/tools/registry.js

@@ -3,7 +3,7 @@ import { listFilesTool } from "./list-files.js";
 import { gitStatusTool } from "./git-status.js";
 import { readFileTool, writeFileTool, editFileTool, applyPatchTool, globTool, grepFilesTool, } from "./file/index.js";
 import { runCommandTool } from "./shell/index.js";
-import { makeRunTestsTool } from "../testing/run-tests-tool.js";
+import { makeRunTestsTool, } from "../testing/run-tests-tool.js";
 import { searchCodebaseTool } from "./search-codebase.js";
 import { listSkillsTool } from "./list-skills.js";
 import { loadSkillTool } from "./load-skill.js";
@@ -55,7 +55,7 @@ function toInputSchema(schema) {
     return json;
 }
 /** Build the default registry with every built-in tool registered. */
-export function buildDefaultRegistry() {
+export function buildDefaultRegistry(opts = {}) {
     const registry = new ToolRegistry();
     registry.register(listFilesTool);
     registry.register(readFileTool);
@@ -67,7 +67,7 @@ export function buildDefaultRegistry() {
     registry.register(gitStatusTool);
     registry.register(runCommandTool);
     // A fresh tool per registry — its iteration budget (C.13) is session-scoped.
-    registry.register(makeRunTestsTool());
+    registry.register(makeRunTestsTool(opts.onTestResult ? { onResult: opts.onTestResult } : {}));
     registry.register(searchCodebaseTool);
     registry.register(listSkillsTool);
     registry.register(loadSkillTool);