@illuminis/comprism 0.1.2 → 0.1.4

package/out/agent/render.js

@@ -22,23 +22,29 @@
  * symbol as well as a color.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.gray = exports.yellow = exports.green = exports.red = exports.bold = exports.dim = void 0;
+exports.violet = exports.gray = exports.yellow = exports.green = exports.red = exports.bold = exports.dim = void 0;
+exports.modelName = modelName;
 exports.money = money;
 exports.duration = duration;
 exports.action = action;
+exports.actionName = actionName;
 exports.reusePct = reusePct;
 exports.step = step;
 exports.todos = todos;
+exports.question = question;
 exports.diff = diff;
+exports.stoppedLines = stoppedLines;
+exports.ending = ending;
 exports.outcome = outcome;
 exports.receipt = receipt;
 exports.plain = plain;
 /** Built from a character code rather than written as a literal escape, so this
  *  file contains no control characters and stays safe to grep, diff and paste. */
 const CSI = String.fromCharCode(27) + "[";
-const supportsColour = process.stdout.isTTY && process.env.NO_COLOR === undefined;
+/** Decided when drawn, so plain mode set at start up applies (manual 6.12). */
+const supportsColour = () => process.stdout.isTTY && !process.env.NO_COLOR;
 function paint(code, text) {
-    return supportsColour ? CSI + code + "m" + text + CSI + "0m" : text;
+    return supportsColour() ? CSI + code + "m" + text + CSI + "0m" : text;
 }
 const dim = (t) => paint("2", t);
 exports.dim = dim;
@@ -52,6 +58,34 @@ const yellow = (t) => paint("33", t);
 exports.yellow = yellow;
 const gray = (t) => paint("90", t);
 exports.gray = gray;
+/** The brand's violet, for model names and the receipt's label. */
+const violet = (t) => paint("38;5;141", t);
+exports.violet = violet;
+/** The rail down the left of a job's steps, as the website draws it. */
+const rail = () => (0, exports.dim)("\u2502");
+const TICK = "\u2713";
+const CROSS = "\u2717";
+/** What a person sees, with color and link escapes taken out, so lines can be
+ *  measured and padded. */
+function visible(text) {
+    const esc = String.fromCharCode(27);
+    return text
+        .replace(new RegExp(`${esc}\\][^${String.fromCharCode(7)}${esc}]*(?:${String.fromCharCode(7)}|${esc}\\\\)`, "g"), "")
+        .replace(new RegExp(`${esc}\\[[0-9;]*m`, "g"), "");
+}
+function width() {
+    return Math.max(60, Math.min(process.stdout.columns || 100, 110));
+}
+/** `claude-haiku-4-5` as a person says it, `Claude Haiku 4.5`. Other vendors'
+ *  ids are shown as they arrive: a wrong guess at a name is worse than the id. */
+function modelName(id) {
+    const m = /^claude-([a-z]+)-(\d+)(?:-(\d+))?$/.exec(id);
+    if (!m)
+        return id;
+    const word = m[1] ?? "";
+    const family = word.charAt(0).toUpperCase() + word.slice(1);
+    return `Claude ${family} ${m[2]}${m[3] ? `.${m[3]}` : ""}`;
+}
 /** Money, at the precision a person can act on.
  *
  *  Four decimal places below a cent, because a coding step often costs less
@@ -70,9 +104,16 @@ function duration(ms) {
 /** One action, as it happens. A word as well as a color, so this still reads
  *  when piped to a file. */
 function action(name, target, ok, ms) {
-    const mark = ok ? (0, exports.green)("ok  ") : (0, exports.red)("fail");
+    // A tick or a cross on the rail, as the website draws a job. A failure also
+    // says so in words, so it still reads in a log with no color.
+    const mark = ok ? (0, exports.green)(TICK) : (0, exports.red)(`${CROSS} failed`);
     const tail = ms ? (0, exports.dim)(`  ${duration(ms)}`) : "";
-    return `  ${mark} ${(0, exports.bold)(name)} ${(0, exports.dim)(target)}${tail}`;
+    return `  ${rail()} ${mark} ${(0, exports.bold)(actionName(name))} ${(0, exports.dim)(target)}${tail}`;
+}
+/** A connected tool as people write it, `server.tool` (manual 9.10). */
+function actionName(name) {
+    const m = /^connected__(.+?)__(.+)$/.exec(name);
+    return m ? `${m[1]}.${m[2]}` : name;
 }
 /** The share of a step's context the provider served from its cache, or null
  *  when it reported no counts. Anthropic counts cached tokens OUTSIDE the input
@@ -89,9 +130,16 @@ function reusePct(tokensIn, cacheRead, cacheWrite) {
  *  provider had already seen. The last figure is the one study 005 found
  *  missing from our receipt: without it nobody could tell a warm step from a
  *  cold one, and every step was cold. */
-function step(index, model, usd, ms, reused = null) {
+function step(index, model, usd, ms, reused = null, reason = "") {
     const warm = reused === null ? "" : `  cached ${reused}%`;
-    return (0, exports.dim)(`  step ${index}  ${model || "?"}  ${money(usd)}  ${duration(ms)}${warm}`);
+    // The model that ran and why, in the service's words (manual 4.16).
+    const why = reason ? `  chosen: ${reason}` : "";
+    // The step and why its model was chosen on the left, the model on the right,
+    // as the website draws a job; the cost and timing follow, quieter.
+    const left = `  ${rail()} ${(0, exports.dim)(`step ${index}${why}`)}`;
+    const right = `${(0, exports.violet)(modelName(model || "?"))}${(0, exports.dim)(`  ${money(usd)}  ${duration(ms)}${warm}`)}`;
+    const gap = Math.max(2, width() - visible(left).length - visible(right).length - 2);
+    return `${left}${" ".repeat(gap)}${right}`;
 }
 /** The task list, reprinted whenever it changes.
  *
@@ -99,24 +147,33 @@ function step(index, model, usd, ms, reused = null) {
  *  is worth keeping, and it is often the fastest way to see where a job went off
  *  course. */
 function todos(items) {
+    // Drawn as manual 4.4 shows it: [x] done, [>] in progress, [ ] not yet.
     if (!items.length)
         return "";
     const rows = items.map((t) => {
-        const mark = t.status === "completed" ? (0, exports.green)("done")
-            : t.status === "in_progress" ? (0, exports.yellow)("now ") : (0, exports.dim)("todo");
+        const mark = t.status === "completed" ? (0, exports.green)("[x]")
+            : t.status === "in_progress" ? (0, exports.yellow)("[>]") : (0, exports.dim)("[ ]");
         const text = t.status === "completed" ? (0, exports.dim)(t.content) : t.content;
-        return `    ${mark}  ${text}`;
+        return `  ${mark} ${text}`;
     });
-    return `\n  ${(0, exports.bold)("Plan")}\n${rows.join("\n")}\n`;
+    return `${rows.join("\n")}\n`;
+}
+/** A question from the agent, or the plan question (manual 4.2, 4.3). The
+ *  wording is the service's; this only lays it out. */
+function question(q, options) {
+    const lines = [`  ${(0, exports.bold)("Question:")} ${q}`];
+    options.forEach((o, i) => lines.push(`  ${i + 1}  ${o}`));
+    return `\n${lines.join("\n")}\n`;
 }
 /** A change, before it is made.
  *
  *  Full text for a small edit and a summary for a large one. Pasting four
  *  hundred lines into a terminal is not review, it is a wall somebody presses
  *  through, and an approval people press through protects nobody. */
-function diff(name, input) {
+function diff(name, input, withHead = true) {
     const target = String(input.path ?? input.to ?? "");
-    const head = `\n  ${(0, exports.bold)(name)} ${target}\n`;
+    // Without the heading under an action line that already names the file.
+    const head = withHead ? `\n  ${(0, exports.bold)(name)} ${target}\n` : "";
     const show = (from, to) => {
         const before = from.split("\n"), after = to.split("\n");
         if (before.length + after.length > 60) {
@@ -142,6 +199,12 @@ function diff(name, input) {
         }
         return head + `    ${(0, exports.dim)(`${lines.length} lines, ${bodyText.length.toLocaleString()} characters`)}\n`;
     }
+    if (name === "git_commit") {
+        // What will be committed, shown before it is (manual 5.17).
+        const files = input.paths ?? [];
+        return `\n  ${(0, exports.bold)("git_commit")}\n    files    ${files.join(", ") || (0, exports.dim)("none")}\n`
+            + `    message  ${String(input.message ?? "").split("\n")[0]}\n`;
+    }
     if (name === "run_command" || name === "run_background") {
         return `\n  ${(0, exports.bold)("run")} ${String(input.command ?? "")}\n`;
     }
@@ -154,6 +217,22 @@ function diff(name, input) {
     }
     return head;
 }
+/** What was stopped when a session ended, one line each (manual 5.13). */
+function stoppedLines(stopped) {
+    if (!stopped.length)
+        return "";
+    return (0, exports.dim)(`  stopped the background process${stopped.length === 1 ? "" : "es"} this session started:\n`)
+        + stopped.map((l) => (0, exports.dim)(`    ${l}\n`)).join("");
+}
+/** The first line of a finished job, as the service wrote it (manual 5.15).
+ *  Colored by its first word only; the words are the service's. */
+function ending(line, detail) {
+    const paint = /^Done$/.test(line) ? exports.green : /^Done,/.test(line) ? exports.yellow
+        : /^(Stopped|Incomplete)/.test(line) ? exports.red : (t) => t;
+    // The service may put the same words in both; they are said once.
+    const extra = detail && detail !== line ? (0, exports.dim)(`  ${detail}`) : "";
+    return `\n${paint(line)}${extra}\n`;
+}
 /** How the job ended, in the words a person reads. */
 function outcome(o, detail) {
     const word = {
@@ -163,6 +242,8 @@ function outcome(o, detail) {
         spend_limit: (0, exports.yellow)("Stopped at the spending limit"),
         failed: (0, exports.red)("Could not finish"),
         refused: (0, exports.red)("Refused"),
+        busy: (0, exports.yellow)("Busy"),
+        unknown: (0, exports.yellow)("Outcome unknown"),
     };
     return `\n${word[o] ?? o}${detail ? (0, exports.dim)(`  ${detail}`) : ""}\n`;
 }
@@ -224,7 +305,69 @@ function receipt(text, models = [], testsPassed) {
     if (testsPassed !== undefined) {
         lines.push(testsPassed ? (0, exports.green)("  tests passed") : (0, exports.red)("  tests failed"));
     }
-    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+    if (!lines.length)
+        return "";
+    // On a screen, the receipt is a highlighted box, as on the website. Piped to
+    // a file or another program it stays plain lines, which is what a log wants.
+    return process.stdout.isTTY ? boxed(text, models, testsPassed) : `${lines.join("\n")}\n`;
+}
+/** Words wrapped to a width, never breaking a word. */
+function wrap(text, room) {
+    const out = [];
+    let line = "";
+    for (const word of text.split(/\s+/).filter(Boolean)) {
+        if (line && line.length + 1 + word.length > room) {
+            out.push(line);
+            line = word;
+        }
+        else
+            line = line ? `${line} ${word}` : word;
+    }
+    if (line)
+        out.push(line);
+    return out;
+}
+/**
+ * The receipt in a rounded box: `receipt` as its label, the saving in green,
+ * everything else quiet. The server's words are unchanged; each clause it
+ * separated with `|` gets its own line, and its link goes last, clickable.
+ */
+function boxed(text, models, testsPassed) {
+    // Room for the border, the padding and the `receipt` label on the first line.
+    const inner = width() - 16;
+    const rows = [];
+    const links = [];
+    for (const raw of String(text || "").split("\n")) {
+        const withoutLinks = raw.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, label, url) => {
+            links.push({ label: String(label), url: String(url) });
+            return "";
+        });
+        for (const clause of withoutLinks.split("|").map((c) => c.trim()).filter(Boolean)) {
+            const paintIt = /\bsaved\b/i.test(clause) ? exports.green : exports.dim;
+            for (const piece of wrap(clause, inner))
+                rows.push(paintIt(piece));
+        }
+    }
+    const priced = models.filter((m) => m.model);
+    if (priced.length > 1) {
+        const order = [...priced].sort((a, b) => (a.usd ?? 0) - (b.usd ?? 0));
+        const w = Math.max(...order.map((m) => modelName(String(m.model)).length));
+        for (const m of order) {
+            const steps = `${m.steps} step${m.steps === 1 ? "" : "s"}`;
+            const cost = m.usd === null || m.usd === undefined ? "not priced" : money(m.usd);
+            rows.push(`${(0, exports.violet)(modelName(String(m.model)).padEnd(w))}${(0, exports.dim)(`  ${steps.padEnd(9)}  ${cost}`)}`);
+        }
+    }
+    if (testsPassed !== undefined)
+        rows.push(testsPassed ? (0, exports.green)("tests passed") : (0, exports.red)("tests failed"));
+    for (const l of links)
+        rows.push((0, exports.dim)(link(l.label, l.url)));
+    if (rows.length)
+        rows[0] = `${(0, exports.violet)("receipt")} ${rows[0]}`;
+    const widest = Math.max(...rows.map((r) => visible(r).length));
+    const bar = "\u2500".repeat(widest + 2);
+    const body = rows.map((r) => `  ${(0, exports.violet)("\u2502")} ${r}${" ".repeat(widest - visible(r).length)} ${(0, exports.violet)("\u2502")}`);
+    return [`  ${(0, exports.violet)(`\u256d${bar}\u256e`)}`, ...body, `  ${(0, exports.violet)(`\u2570${bar}\u256f`)}`].join("\n") + "\n";
 }
 /**
  * Plain text, from a model that writes markdown.

package/out/agent/session.d.ts

@@ -1,3 +1,4 @@
+import { type ProjectFacts } from "../lib/project";
 import * as ui from "./render";
 export interface SessionOptions {
     /** Where the workspace lives, and the URL of the server that owns it. */
@@ -5,6 +6,9 @@ export interface SessionOptions {
     /** The workspace credential the device flow minted. Never a decodable token. */
     credential: string;
     root: string;
+    /** The project, start folder, branch and added folders (manual 2.1 to 2.3).
+     *  `root` is the project root when this is present. */
+    project?: ProjectFacts;
     /** read_only, approve_writes, auto_edit or full_auto. Named, not numbered. */
     permissionMode?: string;
     /** Investigate and propose, change nothing. */
@@ -23,6 +27,25 @@ export interface SessionOptions {
      *  corpus study, which has to measure each model as itself. */
     pinModel?: boolean;
     maxSpendUsd?: number;
+    /** Stop after this many steps (manual 4.13). */
+    maxSteps?: number;
+    /** Reasoning effort asked for: low, medium or high (manual 4.18). */
+    effort?: string;
+    /** Commands run in the operating system's sandbox (manual 4.12). */
+    sandbox?: boolean;
+    /** Seconds each command may run (manual 5.12); the service applies it. */
+    commandTimeoutS?: number;
+    /** Background processes outlive the job; the session stops them (5.13). */
+    keepProcesses?: boolean;
+    /** Start from this GitHub issue (manual 5.20). */
+    issue?: number;
+    /** Lead this team (manual 5.27). */
+    team?: string;
+    /** A review job (manual 5.19). */
+    review?: {
+        pr?: number;
+        post?: boolean;
+    };
     /** Commands the person has approved in advance, matched exactly.
      *
      *  The one thing a run with nobody watching cannot otherwise do is verify its
@@ -35,6 +58,8 @@ export interface SessionOptions {
      *  Ids only: the server holds the text for half an hour and nothing here has
      *  ever seen the contents. */
     attachmentIds?: string[];
+    /** Files named that could not be attached. Names only (manual 3.10). */
+    leftOut?: string[];
     /** Nobody is at the keyboard. Approvals cannot be asked for, so the
      *  permission mode has to have settled them in advance. */
     headless?: boolean;
@@ -47,6 +72,10 @@ export interface SessionOptions {
      *  process owns the keyboard and lends it here. Absent, this class opens its
      *  own reader as before, which is the standalone command's case. */
     confirm?: (question: string) => Promise<boolean>;
+    /** Ask the person for a line of text on the same lent keyboard: the plan
+     *  question and the agent's questions (manual 4.2, 4.3). Resolves null when
+     *  the person pressed Ctrl+C, which stops the job. */
+    prompt?: (question: string) => Promise<string | null>;
     /** Continue a job that already exists, rather than starting one. */
     resumeJobId?: string;
     /** The job this question follows on from. The server loads that job's
@@ -55,6 +84,27 @@ export interface SessionOptions {
     continuesJob?: string;
     /** Go without the code map for this job. See `command.ts`. */
     withoutMap?: boolean;
+    /**
+     * Which conversation this job belongs to.
+     *
+     * Sent because the server cannot work it out. With no conversation id it
+     * files the work under a person's DAY on one client, so three separate
+     * sessions in one afternoon were stored as one row called "cli, 2026-09-21"
+     * and the terminal's own session list disagreed with the Sessions screen.
+     * The terminal has always known which session it was in; it simply never
+     * said.
+     */
+    conversationId?: string;
+    /** `--max-minutes` (manual 10.7), held by the service. */
+    maxMinutes?: number;
+    /** `--schema`, `--config`, `--no-personal` (manual 10.5, 10.8), sent as read. */
+    answerSchema?: Record<string, unknown>;
+    settingsConfig?: Record<string, unknown>;
+    noPersonal?: boolean;
+    /** A queued job this run carries out (manual 10.17 to 10.19). */
+    queuedJob?: string;
+    /** `--output stream`: handed the service's stream lines as they arrive. */
+    onStream?: (items: Array<Record<string, unknown>>) => void;
 }
 export interface JobResult {
     outcome: string;
@@ -77,10 +127,37 @@ export interface JobResult {
     models: ui.ModelShare[];
     text: string;
     testsPassed?: boolean;
+    /** How the job ended, in the service's words (manual 5.15): the first line,
+     *  the proof lines and the exit status. Absent from an older service. */
+    ending?: {
+        line: string | null;
+        proof: string[];
+        exit: number | null;
+        reason?: string;
+    };
+    /** The result object a script reads (manual 10.3), exactly as the service
+     *  built it. Printed with --output json; never assembled here. */
+    result?: Record<string, unknown>;
+    /** Reason word to exit number, as the service sent it (Appendix B). */
+    exitStatus?: Record<string, number>;
+    /** Why the job was refused before it started, as a reason word: the
+     *  service's own, or what the reply showed (no sign in, no connection). */
+    refusalReason?: string;
     /** Share of everything the job sent that the provider served from cache. */
     reusedPct?: number | null;
+    /** The agent's checklist as it ended (manual 4.4). */
+    todos: Array<{
+        content: string;
+        status: string;
+    }>;
+    /** The full reason for the last step's model, for `why` (manual 4.16). */
+    why?: string[];
+    /** Notes typed after the last step, to be sent as new requests (6.8). */
+    lateNotes: string[];
 }
 export declare class TerminalSession {
+    /** The VS Code window this terminal is inside, when there is one (VS Code manual 9.12). */
+    private editor;
     private socket;
     private readonly executor;
     private readonly opts;
@@ -122,8 +199,13 @@ export declare class TerminalSession {
      *  the run frame already sends as the workspace. One expression, so the map
      *  and the job record can never be about two different projects. */
     private project;
+    /** Connections lost during this job, so reconnecting gives up in the end. */
+    private drops;
     /** Why the one service would not start this job, in its own words. */
     private refusal;
+    private refusalReason;
+    private refusalResult;
+    private refusalTable;
     /** The workspace does not carry the permission question yet, so fall back. */
     private olderWorkspace;
     /** Set while one is actually running, so two never overlap. */
@@ -152,11 +234,64 @@ export declare class TerminalSession {
     private remap;
     /** Run one request to its end. Resolves with how it went. */
     run(request: string): Promise<JobResult>;
-    /** Stop the running job. Takes effect mid action, not at the end of the run. */
+    /**
+     * A pass to rejoin this job after a dropped connection, trying for about
+     * half a minute, inside the service's window (manual 8.9). Null when the
+     * service could not be reached again, or refused.
+     */
+    private reconnect;
+    /** Stop the running job. Takes effect mid action, not at the end of the run:
+     *  a command already running on this machine is stopped too (manual 6.7). */
     cancel(): void;
-    /** Something typed while it works. Joins the conversation at the next step. */
+    /** Something typed while it works. Joins the conversation at the next step;
+     *  the service says so in the `note` event it sends back (6.8). */
     steer(text: string): void;
+    /** Esc: finish the current action, then wait (manual 6.7). */
+    pause(): void;
+    /** Carry on after Esc, with a correction or without one. */
+    carryOn(text: string): void;
+    /** This job's id, once the service has issued it (`transcript`, 6.9). */
+    jobId: string | undefined;
+    /** Set from Esc until the job carries on or stops. */
+    paused: boolean;
+    /** Helpers running now, from the service's own events (manual 5.25). */
+    readonly helpers: Map<string, {
+        id: string;
+        question: string;
+        agent?: string | null;
+    }>;
+    /** `stop h2` (5.25): the service stops that one helper. */
+    stopHelper(id: string): void;
+    /** `queue` and `queue clear` (6.8): the service answers with the notes. */
+    queue(clear: boolean): void;
+    /** Ctrl+O: each action's full input and output, or the short line (6.9). */
+    full: boolean;
     private announce;
+    /** The allowance and plan notes, printed under the first line so it stays first. */
+    private allowanceLine;
+    /** A running command's output on screen (manual 5.12): the first lines as
+     *  they arrive, then held, and at the end either the rest or the last lines
+     *  with a count of what was left out. How many is the service's number. */
+    private screen;
+    private stream;
+    private flushScreen;
+    /** Changes already put in front of the person to approve, so they are not
+     *  shown twice. Every other change is shown as it is made (5.6 to 5.8). */
+    private asked;
+    /** The sandbox this machine offers, worked out once (manual 4.12). */
+    private sandboxChecked;
+    private sandboxSystem;
+    /** The full reason for the last step, as the service wrote it (4.16). */
+    lastWhy: string[];
+    /** An unattended run refused an action that needed approval (Appendix B, 4). */
+    refusedUnattended: boolean;
+    /** Approved actions by call, and what exactly was approved (manual 4.8). */
+    private approvedCalls;
+    /** Approvals waiting here that the browser may answer first (web manual 6.15). */
+    private answeredElsewhere;
+    /** An action as approved: its name, its arguments and the real folder it
+     *  runs in, so a changed argument or a moved folder is caught. */
+    private fingerprint;
     private narrate;
     private targetOf;
     /** Put a change in front of the person and wait.
@@ -171,5 +306,9 @@ export declare class TerminalSession {
      *  a script that needs to change files says so by choosing a mode that allows
      *  it, up front. */
     private ask;
+    /** The plan question or one of the agent's questions (manual 4.2, 4.3).
+     *  Returns what the person typed, or null for Ctrl+C. The meaning of the
+     *  answer (y, n, a number, words) is decided by the service. */
+    private question;
     private report;
 }