@illuminis/comprism 0.1.0

package/out/agent/render.d.ts

@@ -0,0 +1,97 @@
+/**
+ * What a coding agent looks like in a terminal.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items A6 (a real coding agent in the terminal), I8 (a terminal panel, real
+ * output, watchable) and I3 (a live action timeline).
+ *
+ * A terminal has no panels, so the whole interface is a stream of lines and the
+ * scrollback IS the record. That constrains everything here:
+ *
+ * **Every line has to make sense on its own, later.** Somebody scrolls back
+ * through a twenty minute run looking for the moment it went wrong. A line that
+ * only means something next to the line above it has failed them.
+ *
+ * **Nothing is redrawn or erased.** Spinners that rewrite their own line leave
+ * nothing behind, and a terminal being piped to a file fills with escape codes.
+ * What is printed stays printed.
+ *
+ * **Color is never the only signal.** Terminals get piped, logged and read by
+ * people who cannot separate red from green, so every state carries a word or a
+ * symbol as well as a color.
+ */
+export declare const dim: (t: string) => string;
+export declare const bold: (t: string) => string;
+export declare const red: (t: string) => string;
+export declare const green: (t: string) => string;
+export declare const yellow: (t: string) => string;
+export declare const gray: (t: string) => string;
+/** Money, at the precision a person can act on.
+ *
+ *  Four decimal places below a cent, because a coding step often costs less
+ *  than one and rounding to $0.00 would show the cheapest work, which is what
+ *  this product is best at, as free. */
+export declare function money(usd: number | null | undefined): string;
+export declare function duration(ms: number | null | undefined): string;
+/** One action, as it happens. A word as well as a color, so this still reads
+ *  when piped to a file. */
+export declare function action(name: string, target: string, ok: boolean, ms?: number): string;
+/** 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
+ *  figure, so the whole context is the three counts added together. */
+export declare function reusePct(tokensIn: number | null | undefined, cacheRead: number | null | undefined, cacheWrite: number | null | undefined): number | null;
+/** One model call: which model, what it cost, and how much of its context the
+ *  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. */
+export declare function step(index: number, model: string, usd: number | null, ms: number | null, reused?: number | null): string;
+/** The task list, reprinted whenever it changes.
+ *
+ *  Reprinted rather than redrawn in place: what the agent intended at each point
+ *  is worth keeping, and it is often the fastest way to see where a job went off
+ *  course. */
+export declare function todos(items: Array<{
+    content: string;
+    status: string;
+}>): string;
+/** 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. */
+export declare function diff(name: string, input: Record<string, unknown>): string;
+/** How the job ended, in the words a person reads. */
+export declare function outcome(o: string, detail: string | null | undefined): string;
+/** One model's share of a job, as our server reported it. */
+export interface ModelShare {
+    model: string | null;
+    steps: number;
+    usd: number | null;
+    unpriced?: number;
+}
+/**
+ * The receipt under a finished job.
+ *
+ * ── The terminal does not compute this, and must not ──────────────────────
+ *
+ * This used to assemble its own sentence from four loose numbers, so the
+ * terminal quoted a different receipt from the browser and the desktop app for
+ * the same job: no models, no comparison model and no saving, which is the
+ * entire claim the product is sold on.
+ *
+ * Our server owns the receipt. It holds the price list, the comparison model
+ * and the arithmetic, it writes the wording once, and every client shows that
+ * wording. All this function does is make it read well in a terminal: indent
+ * it, quieten it, and turn the address in it into something clickable. That is
+ * formatting, which belongs to the client, and it is the only part that does.
+ */
+export declare function receipt(text: string, models?: ModelShare[], testsPassed?: boolean): string;
+/**
+ * Plain text, from a model that writes markdown.
+ *
+ * A terminal has no bold and no bullet glyphs, so `**like this**` arrives on
+ * screen as literal asterisks and a heading looks like a typing mistake. The
+ * emphasis is real, so it is kept as terminal bold rather than thrown away;
+ * everything that only exists to be rendered by a browser is removed.
+ */
+export declare function plain(text: string): string;

package/out/agent/render.js

@@ -0,0 +1,255 @@
+"use strict";
+/**
+ * What a coding agent looks like in a terminal.
+ *
+ * Specification: docs/modules/CODING_AGENT_BUILD_SPECIFICATION.md, register
+ * items A6 (a real coding agent in the terminal), I8 (a terminal panel, real
+ * output, watchable) and I3 (a live action timeline).
+ *
+ * A terminal has no panels, so the whole interface is a stream of lines and the
+ * scrollback IS the record. That constrains everything here:
+ *
+ * **Every line has to make sense on its own, later.** Somebody scrolls back
+ * through a twenty minute run looking for the moment it went wrong. A line that
+ * only means something next to the line above it has failed them.
+ *
+ * **Nothing is redrawn or erased.** Spinners that rewrite their own line leave
+ * nothing behind, and a terminal being piped to a file fills with escape codes.
+ * What is printed stays printed.
+ *
+ * **Color is never the only signal.** Terminals get piped, logged and read by
+ * people who cannot separate red from green, so every state carries a word or a
+ * 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.money = money;
+exports.duration = duration;
+exports.action = action;
+exports.reusePct = reusePct;
+exports.step = step;
+exports.todos = todos;
+exports.diff = diff;
+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;
+function paint(code, text) {
+    return supportsColour ? CSI + code + "m" + text + CSI + "0m" : text;
+}
+const dim = (t) => paint("2", t);
+exports.dim = dim;
+const bold = (t) => paint("1", t);
+exports.bold = bold;
+const red = (t) => paint("31", t);
+exports.red = red;
+const green = (t) => paint("32", t);
+exports.green = green;
+const yellow = (t) => paint("33", t);
+exports.yellow = yellow;
+const gray = (t) => paint("90", t);
+exports.gray = gray;
+/** Money, at the precision a person can act on.
+ *
+ *  Four decimal places below a cent, because a coding step often costs less
+ *  than one and rounding to $0.00 would show the cheapest work, which is what
+ *  this product is best at, as free. */
+function money(usd) {
+    if (usd === null || usd === undefined)
+        return "unpriced";
+    return usd < 0.01 ? `$${usd.toFixed(4)}` : `$${usd.toFixed(2)}`;
+}
+function duration(ms) {
+    if (!ms)
+        return "";
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+/** 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");
+    const tail = ms ? (0, exports.dim)(`  ${duration(ms)}`) : "";
+    return `  ${mark} ${(0, exports.bold)(name)} ${(0, exports.dim)(target)}${tail}`;
+}
+/** 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
+ *  figure, so the whole context is the three counts added together. */
+function reusePct(tokensIn, cacheRead, cacheWrite) {
+    if (cacheRead === null || cacheRead === undefined)
+        return null;
+    const whole = (tokensIn ?? 0) + (cacheRead ?? 0) + (cacheWrite ?? 0);
+    if (!whole)
+        return null;
+    return Math.round((cacheRead / whole) * 100);
+}
+/** One model call: which model, what it cost, and how much of its context the
+ *  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) {
+    const warm = reused === null ? "" : `  cached ${reused}%`;
+    return (0, exports.dim)(`  step ${index}  ${model || "?"}  ${money(usd)}  ${duration(ms)}${warm}`);
+}
+/** The task list, reprinted whenever it changes.
+ *
+ *  Reprinted rather than redrawn in place: what the agent intended at each point
+ *  is worth keeping, and it is often the fastest way to see where a job went off
+ *  course. */
+function todos(items) {
+    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 text = t.status === "completed" ? (0, exports.dim)(t.content) : t.content;
+        return `    ${mark}  ${text}`;
+    });
+    return `\n  ${(0, exports.bold)("Plan")}\n${rows.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) {
+    const target = String(input.path ?? input.to ?? "");
+    const head = `\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) {
+            return `    ${(0, exports.dim)(`${before.length} lines replaced by ${after.length} lines`)}\n`;
+        }
+        return [
+            ...before.map((l) => `    ${(0, exports.red)("-")} ${l}`),
+            ...after.map((l) => `    ${(0, exports.green)("+")} ${l}`),
+        ].join("\n") + "\n";
+    };
+    if (name === "edit_file") {
+        return head + show(String(input.old_text ?? ""), String(input.new_text ?? ""));
+    }
+    if (name === "multi_edit") {
+        const edits = input.edits ?? [];
+        return head + edits.map((e) => show(e.old_text, e.new_text)).join(`    ${(0, exports.dim)("--")}\n`);
+    }
+    if (name === "write_file") {
+        const bodyText = String(input.content ?? "");
+        const lines = bodyText.split("\n");
+        if (lines.length <= 40) {
+            return head + lines.map((l) => `    ${(0, exports.green)("+")} ${l}`).join("\n") + "\n";
+        }
+        return head + `    ${(0, exports.dim)(`${lines.length} lines, ${bodyText.length.toLocaleString()} characters`)}\n`;
+    }
+    if (name === "run_command" || name === "run_background") {
+        return `\n  ${(0, exports.bold)("run")} ${String(input.command ?? "")}\n`;
+    }
+    if (name === "install_dependency") {
+        return `\n  ${(0, exports.bold)("install")} ${String(input.package ?? "")}`
+            + `  ${(0, exports.dim)("(this changes the lockfile for everyone who works here)")}\n`;
+    }
+    if (name === "delete_file") {
+        return head + `    ${(0, exports.dim)("A copy is kept, so this can be undone.")}\n`;
+    }
+    return head;
+}
+/** How the job ended, in the words a person reads. */
+function outcome(o, detail) {
+    const word = {
+        finished: (0, exports.green)("Done"),
+        cancelled: (0, exports.yellow)("Stopped"),
+        step_limit: (0, exports.yellow)("Stopped after too many steps"),
+        spend_limit: (0, exports.yellow)("Stopped at the spending limit"),
+        failed: (0, exports.red)("Could not finish"),
+        refused: (0, exports.red)("Refused"),
+    };
+    return `\n${word[o] ?? o}${detail ? (0, exports.dim)(`  ${detail}`) : ""}\n`;
+}
+/**
+ * A link a person can click, where the terminal supports one.
+ *
+ * Modern terminals understand an escape that carries an address behind a piece
+ * of text; older ones print it as ordinary characters, so the address is shown
+ * in words there instead. Never a bare escape with no fallback: a receipt whose
+ * proof is unreachable is not proof.
+ */
+function link(text, url) {
+    if (!process.stdout.isTTY)
+        return `${text} (${url})`;
+    return `]8;;${url}${text}]8;;`;
+}
+/**
+ * The receipt under a finished job.
+ *
+ * ── The terminal does not compute this, and must not ──────────────────────
+ *
+ * This used to assemble its own sentence from four loose numbers, so the
+ * terminal quoted a different receipt from the browser and the desktop app for
+ * the same job: no models, no comparison model and no saving, which is the
+ * entire claim the product is sold on.
+ *
+ * Our server owns the receipt. It holds the price list, the comparison model
+ * and the arithmetic, it writes the wording once, and every client shows that
+ * wording. All this function does is make it read well in a terminal: indent
+ * it, quieten it, and turn the address in it into something clickable. That is
+ * formatting, which belongs to the client, and it is the only part that does.
+ */
+function receipt(text, models = [], testsPassed) {
+    const lines = [];
+    for (const line of String(text || "").split("\n")) {
+        if (!line.trim())
+            continue;
+        // The address our server put in the sentence becomes a real link, and the
+        // words around it are left exactly as they were written.
+        const shown = line.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, label, url) => link(String(label), String(url)));
+        lines.push((0, exports.dim)(`  ${shown}`));
+    }
+    // Which models did the work, cheapest first, because the cheap ones doing
+    // most of the steps IS the mechanism and a reader should see it at a glance.
+    const priced = models.filter((m) => m.model);
+    if (priced.length > 1) {
+        const order = [...priced].sort((a, b) => (a.usd ?? 0) - (b.usd ?? 0));
+        const width = Math.max(...order.map((m) => 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
+                // Never a zero standing in for a price nobody has. A step we could not
+                // price is said so, because a total that hides one is a smaller total.
+                ? "not priced"
+                : money(m.usd);
+            lines.push((0, exports.dim)(`    ${String(m.model).padEnd(width)}  ${steps.padEnd(9)}  ${cost}`));
+        }
+    }
+    if (testsPassed !== undefined) {
+        lines.push(testsPassed ? (0, exports.green)("  tests passed") : (0, exports.red)("  tests failed"));
+    }
+    return lines.length > 0 ? `${lines.join("\n")}\n` : "";
+}
+/**
+ * Plain text, from a model that writes markdown.
+ *
+ * A terminal has no bold and no bullet glyphs, so `**like this**` arrives on
+ * screen as literal asterisks and a heading looks like a typing mistake. The
+ * emphasis is real, so it is kept as terminal bold rather than thrown away;
+ * everything that only exists to be rendered by a browser is removed.
+ */
+function plain(text) {
+    return text
+        // Fenced code keeps its content and loses its fence markers.
+        .replace(/^```[a-zA-Z0-9]*\n?/gm, '')
+        .replace(/^```$/gm, '')
+        // Headings become their own words, emphasized.
+        .replace(/^#{1,6}\s+(.+)$/gm, (_m, t) => (0, exports.bold)(String(t)))
+        // Bold and italic become the terminal's own emphasis.
+        .replace(/\*\*([^*]+)\*\*/g, (_m, t) => (0, exports.bold)(String(t)))
+        .replace(/__([^_]+)__/g, (_m, t) => (0, exports.bold)(String(t)))
+        .replace(/(^|[^*])\*([^*\n]+)\*/g, (_m, pre, t) => pre + String(t))
+        // A bullet is a bullet, not an asterisk.
+        .replace(/^\s*[*-]\s+/gm, '  . ')
+        // Inline code keeps its text; the backticks were never for a terminal.
+        .replace(/`([^`]+)`/g, (_m, t) => String(t))
+        // A link reads as its words, with the address after it.
+        .replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, t, u) => `${t} (${u})`)
+        .replace(/\n{3,}/g, '\n\n');
+}

package/out/agent/session.d.ts

@@ -0,0 +1,175 @@
+import * as ui from "./render";
+export interface SessionOptions {
+    /** Where the workspace lives, and the URL of the server that owns it. */
+    baseUrl: string;
+    /** The workspace credential the device flow minted. Never a decodable token. */
+    credential: string;
+    root: string;
+    /** read_only, approve_writes, auto_edit or full_auto. Named, not numbered. */
+    permissionMode?: string;
+    /** Investigate and propose, change nothing. */
+    planOnly?: boolean;
+    /** The plan was read and approved, so the files in it are not asked about
+     *  again. The server checks this against what the account permits; sending it
+     *  is a statement of what the person said, not a grant. */
+    planApproved?: boolean;
+    /** A model the person named. Absent means the router chooses, per step, which
+     *  is the point of the product. On its own this TELLS the router what is
+     *  running, so the receipt can price the saving against it; the router is
+     *  still free to move up. Set `pinModel` to be given that model and no other. */
+    model?: string;
+    /** Run `model` and nothing else, whatever the router would prefer. Off by
+     *  default. For a person who wants to decide for themselves, and for the
+     *  corpus study, which has to measure each model as itself. */
+    pinModel?: boolean;
+    maxSpendUsd?: number;
+    /** Commands the person has approved in advance, matched exactly.
+     *
+     *  The one thing a run with nobody watching cannot otherwise do is verify its
+     *  own work: every mode asks before running an arbitrary command, correctly,
+     *  and there is nobody there to answer. Naming the command up front is how
+     *  that is settled without widening anything, which is why it is a list of
+     *  exact commands and not a flag that turns the check off. */
+    approvedCommands?: string[];
+    /** Files already uploaded and waiting, to be read before this question.
+     *  Ids only: the server holds the text for half an hour and nothing here has
+     *  ever seen the contents. */
+    attachmentIds?: string[];
+    /** Nobody is at the keyboard. Approvals cannot be asked for, so the
+     *  permission mode has to have settled them in advance. */
+    headless?: boolean;
+    /** Ask the person a yes or no question, using a keyboard somebody else
+     *  already owns.
+     *
+     *  A session that is reading its own prompt cannot also let this class open a
+     *  reader: the two divide the typing between them and the second gets
+     *  nothing, so every approval hung or came back refused. Whoever started the
+     *  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>;
+    /** 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
+     *  conversation from the record, so a terminal with no store of its own still
+     *  holds a thread. */
+    continuesJob?: string;
+    /** Go without the code map for this job. See `command.ts`. */
+    withoutMap?: boolean;
+}
+export interface JobResult {
+    outcome: string;
+    detail?: string | null;
+    jobId?: string;
+    steps: number;
+    actions: number;
+    totalUsd: number;
+    /** What routing saved against the comparison model, or null when there is
+     *  nothing to compare this job against. Never 0 in place of unknown: a saving
+     *  of zero and a saving nobody can price are different answers. */
+    savedUsd: number | null;
+    /** The receipt sentence, exactly as our server wrote it. The terminal
+     *  formats this and never composes its own: the price list, the comparison
+     *  model and the arithmetic are all on the server, so a client that wrote its
+     *  own wording would be a second answer to the same question. */
+    receipt: string;
+    /** Which models did the work, and each one's share, as the server reported
+     *  it. Taken as sent, never recalculated here. */
+    models: ui.ModelShare[];
+    text: string;
+    testsPassed?: boolean;
+    /** Share of everything the job sent that the provider served from cache. */
+    reusedPct?: number | null;
+}
+export declare class TerminalSession {
+    private socket;
+    private readonly executor;
+    private readonly opts;
+    private readonly out;
+    private lastTodos;
+    /** The last thing it said on screen, so the ending does not say it twice.
+     *  Every step prints what the model said, and the closing frame carries the
+     *  final text again, so the answer to a one step job appeared twice in a row
+     *  with nothing between the copies. */
+    private lastSaid;
+    private canceled;
+    constructor(opts: SessionOptions, write?: (s: string) => void);
+    /** Where the socket lives, derived from the workspace URL.
+     *
+     *  Derived rather than configured: a second setting for the socket address is
+     *  a second thing that can point at the wrong server, and the failure would be
+     *  a job running against somebody else's workspace. */
+    /**
+     * A pass for this job's stream, from the one service.
+     *
+     * The job is authorized THERE, where everything else in the product is
+     * authorized, and this returns only permission to open the stream. Null when
+     * the service refused or could not be reached, and the caller then reports
+     * the service's own words rather than guessing at them.
+     */
+    private pass;
+    /** Where the stream lives, derived from the workspace URL.
+     *
+     *  Derived rather than configured: a second setting for the stream address is
+     *  a second thing that can point at the wrong server, and the failure would be
+     *  a job running against somebody else's workspace.
+     *
+     *  The credential still travels because the pass is redeemed against the
+     *  tenant it was issued in, and the pass is what actually authorizes the job.
+     *  Without a pass this falls back to the old behavior, which is what a
+     *  workspace running an older build still understands. */
+    private socketUrl;
+    /** The name the map is held under: the folder's own, which is exactly what
+     *  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;
+    /** Why the one service would not start this job, in its own words. */
+    private refusal;
+    /** The workspace does not carry the permission question yet, so fall back. */
+    private olderWorkspace;
+    /** Set while one is actually running, so two never overlap. */
+    private remapping;
+    /**
+     * The agent just changed something on disk. Bring the map back in step.
+     *
+     * Only for actions that can change a file. A read or a search leaves the
+     * project exactly as it was, and re-reading it would be a round trip bought
+     * for nothing on the most common actions there are.
+     *
+     * The refresh itself is the ordinary one: it compares the files against what
+     * the service holds and sends back only what moved, which after one edit is
+     * one file. Debounced by a short wait, because an agent that writes four
+     * files in one step should pay for one update, not four.
+     */
+    private noteChanged;
+    /**
+     * Put the files this job changed back into the map.
+     *
+     * Runs after the job, without being waited on: the person has their answer
+     * and a re-read of three files must not hold up their prompt. A failure here
+     * costs nothing, because the next job checks the files anyway and would read
+     * them then.
+     */
+    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. */
+    cancel(): void;
+    /** Something typed while it works. Joins the conversation at the next step. */
+    steer(text: string): void;
+    private announce;
+    private narrate;
+    private targetOf;
+    /** Put a change in front of the person and wait.
+     *
+     *  Three cases, in order. A caller that owns the keyboard lent us one, so the
+     *  question goes there. Nobody lent one and somebody is watching, so we open
+     *  our own reader. Nobody is watching, so it is refused.
+     *
+     *  In headless mode there is nobody to ask, so it is refused rather than
+     *  assumed. Treating silence as consent would let a script approve changes
+     *  nobody ever saw, which is the opposite of what a permission mode is for:
+     *  a script that needs to change files says so by choosing a mode that allows
+     *  it, up front. */
+    private ask;
+    private report;
+}