glm-coding-router 1.1.2 → 2.1.0

package/dist/tui/progress.js

@@ -0,0 +1,338 @@
+import path from "node:path";
+import { logger } from "../core/logging.js";
+import { ansi, createWriter, paint, truncate } from "./render.js";
+/**
+ * Decide the mode from flags / env / config / TTY-ness. The order is
+ * contractual: an orchestrator's `--quiet` or a CI environment must be able to
+ * force silence even when config asks for rich, while an explicit env override
+ * still beats config so `GLM_ROUTER_PROGRESS=nested glm-worker …` works on a
+ * machine whose config says otherwise. `auto` (the config default) picks rich
+ * for humans at a terminal and nested for everything piped.
+ */
+export function resolveProgressMode(input) {
+    const env = input.env ?? {};
+    if (input.flagOff || input.quiet || env.CI === "true" || env.GLM_ROUTER_PROGRESS === "off") {
+        return "off";
+    }
+    const override = env.GLM_ROUTER_PROGRESS;
+    if (override === "rich" || override === "nested") {
+        return override;
+    }
+    if (env.GLM_ROUTER_NESTED === "1") {
+        return "nested";
+    }
+    const configured = input.configMode;
+    if (configured === "rich" || configured === "nested" || configured === "off") {
+        return configured;
+    }
+    return input.isTTY ? "rich" : "nested";
+}
+/**
+ * Subscribe a progress renderer to the bus. The stream is a parameter, never
+ * `process.stdout`, because that channel belongs to the worker's final answer
+ * (contracts C1/C2) — production callers pass `process.stderr`, tests pass a
+ * memory stream. `detach()` unsubscribes and restores the cursor.
+ */
+export function attachProgress(bus, opts) {
+    if (opts.mode === "off") {
+        // Rendering nothing still needs a uniform handle so callers can detach blindly.
+        return { detach() { } };
+    }
+    // Nested lines are parsed by orchestrators, so that mode defaults to plain
+    // text unless the caller explicitly opts into color; rich keeps the writer's
+    // own TTY/NO_COLOR default.
+    const color = opts.color ?? (opts.mode === "nested" ? false : undefined);
+    const writer = createWriter(opts.stream, { color });
+    const renderer = opts.mode === "nested"
+        ? new NestedRenderer(writer, bus.runId)
+        : new RichRenderer(writer, opts.project);
+    const unsubscribe = bus.subscribe((event) => {
+        // The bus already catches subscriber exceptions; the renderer guards itself
+        // too so a half-broken state machine degrades instead of compounding.
+        try {
+            renderer.handle(event);
+        }
+        catch (error) {
+            logger.debug(`progress renderer threw on ${event.type}: ${errorMessage(error)}`);
+        }
+    });
+    return {
+        detach() {
+            unsubscribe();
+            renderer.close();
+        },
+    };
+}
+/** Last 4 characters of the run id, uppercased — short enough to say aloud. */
+function shortRunId(runId) {
+    return runId.slice(-4).toUpperCase();
+}
+/** Duration in seconds with one decimal, the resolution that is readable and honest. */
+function formatSeconds(durationMs) {
+    return `${(durationMs / 1000).toFixed(1)}s`;
+}
+/**
+ * The one-word verb for a nested turn line. Validators are recognized via the
+ * `ValidationStarted` that the adapter emits immediately before the matching
+ * `ToolStarted`, so no tool-input inspection is needed here (C3).
+ */
+function nestedVerb(tool, isValidation) {
+    if (tool === "Read" || tool === "Grep" || tool === "Glob") {
+        return "exploring";
+    }
+    if (tool === "Edit" || tool === "Write" || tool === "MultiEdit") {
+        return "editing";
+    }
+    if (tool === "Bash") {
+        return isValidation ? "running tests" : "running";
+    }
+    return `using ${tool}`;
+}
+/**
+ * Nested mode: one stable `[GLM] …` line per significant event and no cursor
+ * control, so an orchestrator can `readline` stderr without speaking ANSI.
+ * These lines are a machine interface — change them only for cause.
+ */
+class NestedRenderer {
+    writer;
+    short;
+    /** Turn whose first tool has already been announced; 0 = none. */
+    announcedTurn = 0;
+    /** Turn of a `ValidationStarted` awaiting its `ToolStarted`. */
+    validationTurn = null;
+    finished = false;
+    constructor(writer, runId) {
+        this.writer = writer;
+        this.short = shortRunId(runId);
+    }
+    handle(event) {
+        if (this.finished) {
+            return;
+        }
+        switch (event.type) {
+            case "RunStarted":
+                this.writer.line(`[GLM] ${paint(this.writer, "cyan", "●")} #${this.short} started • ${event.model}`);
+                break;
+            case "ValidationStarted":
+                // Consumed by the ToolStarted that follows it in the same turn.
+                this.validationTurn = event.turn;
+                break;
+            case "ToolStarted": {
+                if (event.turn === this.announcedTurn) {
+                    break; // later tools of a turn print nothing
+                }
+                this.announcedTurn = event.turn;
+                const isValidation = this.validationTurn === event.turn;
+                if (isValidation) {
+                    this.validationTurn = null;
+                }
+                this.writer.line(`[GLM] turn ${event.turn} • ${nestedVerb(event.tool, isValidation)} ${event.summary}`);
+                break;
+            }
+            case "ValidationCompleted":
+                this.writer.line(`[GLM] ${paint(this.writer, event.ok ? "green" : "red", event.ok ? "✓" : "✗")} tests ` +
+                    `${event.ok ? "passed" : "failed"}`);
+                break;
+            case "ToolDenied":
+                this.writer.line(`[GLM] ${paint(this.writer, "yellow", "⚠")} denied: ${event.tool} — ${event.reason}`);
+                break;
+            case "ApiRetry":
+                this.writer.line(`[GLM] ${paint(this.writer, "yellow", "⚠")} retry: ${event.reason}`);
+                break;
+            case "RunCompleted":
+                this.writer.line(`[GLM] ${paint(this.writer, "green", "✓")} #${this.short} • ` +
+                    `${formatSeconds(event.durationMs)} • ${event.turns} turns • ${event.filesChanged} files`);
+                this.finished = true;
+                break;
+            case "RunFailed":
+                this.writer.line(`[GLM] ${paint(this.writer, "red", "✗")} #${this.short} • ${event.reason}`);
+                this.finished = true;
+                break;
+            case "RunCancelled":
+                this.writer.line(`[GLM] ${paint(this.writer, "red", "✗")} #${this.short} • cancelled`);
+                this.finished = true;
+                break;
+            default:
+                break; // TurnStarted, Heartbeat, AgentInitialized, … — deliberately silent
+        }
+    }
+    close() {
+        // No cursor was ever hidden in nested mode.
+    }
+}
+/** Width of the rich header's label column ("Project" + 2 spaces, doc §7). */
+const LABEL_WIDTH = 9;
+/** Width of the rich tool column ("Write" + separator, doc §7). */
+const TOOL_WIDTH = 5;
+/** Width of the footer label column ("Duration" + 3 spaces, doc §7). */
+const FOOTER_LABEL_WIDTH = 11;
+const TITLE_BY_KIND = {
+    worker: "GLM Worker",
+    review: "GLM Review",
+    delegate: "GLM Delegate",
+};
+/**
+ * Rich mode: the doc §7 box header plus a per-turn tool tree. On a TTY the
+ * current turn block is redrawn in place (cursor-up + erase per line); on a
+ * non-TTY stream it appends, one entry behind, so the `└─` connector of the
+ * last-known entry is never written wrong — piped output must stay readable
+ * with zero escape codes, not a pile of them.
+ */
+class RichRenderer {
+    writer;
+    projectName;
+    short = "";
+    currentTurn = 0;
+    /** Plain content lines of the current turn block, connectors excluded. */
+    entries = [];
+    /** TTY: lines of the current block currently on screen (the redraw budget). */
+    drawn = 0;
+    /** non-TTY: entries of the current block already written for good. */
+    flushed = 0;
+    finished = false;
+    cursorHidden = false;
+    constructor(writer, project) {
+        this.writer = writer;
+        this.projectName = project;
+    }
+    handle(event) {
+        if (this.finished) {
+            return;
+        }
+        switch (event.type) {
+            case "RunStarted":
+                this.writeHeader(event);
+                break;
+            case "TurnStarted":
+                this.beginTurn(event.turn);
+                break;
+            case "ToolStarted":
+                // Defensive: a replayed stream without TurnStarted still groups by turn.
+                if (event.turn !== this.currentTurn) {
+                    this.beginTurn(event.turn);
+                }
+                this.addEntry(`${event.tool.padEnd(TOOL_WIDTH)} ${this.summaryFit(event.summary)}`);
+                break;
+            case "ToolDenied":
+                this.addEntry(`${paint(this.writer, "yellow", "⚠")} denied: ${event.tool} — ${this.summaryFit(event.reason)}`);
+                break;
+            case "ApiRetry":
+                this.addEntry(`${paint(this.writer, "yellow", "⚠")} retry: ${this.summaryFit(event.reason)}`);
+                break;
+            case "ValidationCompleted":
+                this.addEntry(`${paint(this.writer, event.ok ? "green" : "red", event.ok ? "✓" : "✗")} tests ` +
+                    `${event.ok ? "passed" : "failed"}`);
+                break;
+            case "RunCompleted":
+                this.writeSuccessFooter(event);
+                break;
+            case "RunFailed":
+                this.writeFailureClose(`✗ Failed — ${event.reason}`);
+                break;
+            case "RunCancelled":
+                this.writeFailureClose("✗ Cancelled");
+                break;
+            default:
+                break; // Heartbeat feeds the registry, not this tree
+        }
+    }
+    close() {
+        this.restoreCursor();
+    }
+    beginTurn(turn) {
+        this.finalizeBlock();
+        this.currentTurn = turn;
+        this.entries.length = 0;
+        this.drawn = 0;
+        this.flushed = 0;
+        this.writer.line(`${paint(this.writer, "cyan", "◉")} Turn ${turn}`);
+    }
+    addEntry(content) {
+        this.entries.push(content);
+        this.refresh();
+    }
+    /** Bring the on-screen representation of the current block up to date. */
+    refresh() {
+        if (this.writer.isTTY) {
+            for (let i = 0; i < this.drawn; i++) {
+                this.writer.write(ansi.cursorUp(1) + ansi.clearLine);
+            }
+            this.drawn = 0;
+            for (const line of this.blockLines()) {
+                this.writer.write(`${line}\n`);
+                this.drawn++;
+            }
+            return;
+        }
+        // Append-only: hold the newest entry back until it is provably not the
+        // last one, because written bytes cannot be taken back.
+        while (this.entries.length - this.flushed >= 2) {
+            this.writer.line(`  ├─ ${this.entries[this.flushed]}`);
+            this.flushed++;
+        }
+    }
+    /** Freeze the current block: previous turns are history and never redrawn. */
+    finalizeBlock() {
+        if (!this.writer.isTTY && this.entries.length > this.flushed) {
+            this.writer.line(`  └─ ${this.entries[this.entries.length - 1]}`);
+            this.flushed = this.entries.length;
+        }
+    }
+    blockLines() {
+        return this.entries.map((content, index) => index === this.entries.length - 1 ? `  └─ ${content}` : `  ├─ ${content}`);
+    }
+    writeHeader(event) {
+        this.short = shortRunId(event.runId);
+        if (this.writer.isTTY) {
+            this.writer.write(ansi.hideCursor);
+            this.cursorHidden = true;
+        }
+        const project = this.projectName ?? (path.basename(event.cwd) || event.cwd);
+        const rows = [
+            `${"Run".padEnd(LABEL_WIDTH)}#${this.short}`,
+            `${"Model".padEnd(LABEL_WIDTH)}${event.model}`,
+            `${"Project".padEnd(LABEL_WIDTH)}${project}`,
+        ];
+        const prefix = `─ ${TITLE_BY_KIND[event.kind]} `;
+        const inner = Math.max(...rows.map((row) => row.length), prefix.length);
+        this.writer.line(`╭${prefix}${"─".repeat(inner + 2 - prefix.length)}╮`);
+        for (const row of rows) {
+            this.writer.line(`│ ${row.padEnd(inner)} │`);
+        }
+        this.writer.line(`╰${"─".repeat(inner + 2)}╯`);
+        this.writer.line();
+    }
+    writeSuccessFooter(event) {
+        this.finalizeBlock();
+        this.writer.line();
+        this.writer.line(`${paint(this.writer, "green", "✓")} Completed`);
+        this.writer.line();
+        this.writer.line(`${"Duration".padEnd(FOOTER_LABEL_WIDTH)}${formatSeconds(event.durationMs)}`);
+        this.writer.line(`${"Turns".padEnd(FOOTER_LABEL_WIDTH)}${event.turns}`);
+        this.writer.line(`${"Files".padEnd(FOOTER_LABEL_WIDTH)}${event.filesChanged}`);
+        this.finish();
+    }
+    writeFailureClose(text) {
+        this.finalizeBlock();
+        this.writer.line();
+        this.writer.line(paint(this.writer, "red", text));
+        this.finish();
+    }
+    finish() {
+        this.finished = true;
+        this.restoreCursor();
+    }
+    restoreCursor() {
+        if (this.cursorHidden) {
+            this.writer.write(ansi.showCursor);
+            this.cursorHidden = false;
+        }
+    }
+    /** Cap a summary to the terminal width so one long path cannot wrap the tree. */
+    summaryFit(text) {
+        return truncate(text, Math.max(20, this.writer.columns - (TOOL_WIDTH + 7)));
+    }
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/tui/render.js

@@ -0,0 +1,144 @@
+/**
+ * Writer abstraction over an injectable output stream (specs/v2-architecture.md,
+ * Phase C, decision D1: dependency-free TUI).
+ *
+ * This is the ONLY file in the codebase that contains ANSI escape sequences, so
+ * swapping the rendering backend later (e.g. Ink) is a contained change. It also
+ * keeps contract C1 testable: a caller injects the stream it wants to assert on,
+ * and this module never touches `process.stdout` or `process.stderr` itself.
+ */
+/**
+ * The escape sequences the TUI needs. Kept as data, not methods on Writer, so
+ * a renderer can compose them (cursorUp + clearLine per redrawn line) in one
+ * write call where the platform batches better.
+ */
+export const ansi = {
+    /** Move the cursor up `n` lines; empty string for n <= 0 (a no-op move). */
+    cursorUp(n) {
+        return n > 0 ? `\u001b[${n}A` : "";
+    },
+    /** Erase the whole current line (cursor column is untouched). */
+    clearLine: "\u001b[2K",
+    hideCursor: "\u001b[?25l",
+    showCursor: "\u001b[?25h",
+};
+const STYLE_CODES = {
+    dim: "\u001b[2m",
+    bold: "\u001b[1m",
+    green: "\u001b[32m",
+    red: "\u001b[31m",
+    yellow: "\u001b[33m",
+    cyan: "\u001b[36m",
+};
+const RESET = "\u001b[0m";
+/**
+ * Wrap `text` in the escape pair for `style`, or return it unchanged when the
+ * writer has color off — piped output must stay byte-clean for machines.
+ */
+export function paint(writer, style, text) {
+    return writer.color ? `${STYLE_CODES[style]}${text}${RESET}` : text;
+}
+/**
+ * Build a Writer over any writable stream. `isTTY`/`columns` are read off the
+ * stream when present (only real terminals have them); `color` defaults to
+ * `isTTY && !NO_COLOR` because honoring NO_COLOR is part of the platform
+ * contract, and an explicit `opts.color` overrides both.
+ */
+export function createWriter(stream, opts) {
+    // NodeJS.WritableStream does not declare terminal-only members, so narrow
+    // through a structural shape instead of trusting the declared type.
+    const terminal = stream;
+    const isTTY = terminal.isTTY === true;
+    const noColor = (process.env.NO_COLOR ?? "").length > 0;
+    const dumbTerm = process.env.TERM === "dumb";
+    const color = opts?.color ?? (isTTY && !noColor && !dumbTerm);
+    return {
+        write(text) {
+            stream.write(text);
+        },
+        line(text) {
+            stream.write((text ?? "") + "\n");
+        },
+        isTTY,
+        color,
+        columns: terminal.columns ?? 80,
+    };
+}
+/**
+ * Terminal display width of one Unicode code point: 0 for combining marks,
+ * variation selectors and control characters, 2 for East Asian Wide/Fullwidth
+ * ranges and common emoji, 1 otherwise. A simplified, dependency-free
+ * approximation of Markus Kuhn's wcwidth (specs/terminal-ui-doctor.md §A
+ * "Width uses display cells, not ANSI string length") — good enough for
+ * layout purposes without pulling in a wcwidth/string-width package, which
+ * would break the TUI's dependency-free design (specs/v2-architecture.md D1).
+ */
+function codePointWidth(cp) {
+    if (cp === 0 ||
+        (cp >= 0x0001 && cp <= 0x001f) ||
+        (cp >= 0x007f && cp <= 0x009f) ||
+        (cp >= 0x0300 && cp <= 0x036f) || // combining diacritical marks
+        (cp >= 0x200b && cp <= 0x200f) || // zero-width space/joiners, LTR/RTL marks
+        cp === 0xfeff || // zero-width no-break space / BOM
+        (cp >= 0xfe00 && cp <= 0xfe0f) || // variation selectors
+        (cp >= 0x20d0 && cp <= 0x20ff) || // combining marks for symbols
+        (cp >= 0x1f3fb && cp <= 0x1f3ff) // emoji skin-tone modifiers
+    ) {
+        return 0;
+    }
+    if ((cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+        (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals, Kangxi, CJK punctuation
+        (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana, Katakana, CJK compat, enclosed CJK
+        (cp >= 0x3400 && cp <= 0x4dbf) || // CJK Unified Ideographs Extension A
+        (cp >= 0x4e00 && cp <= 0x9fff) || // CJK Unified Ideographs
+        (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+        (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+        (cp >= 0xf900 && cp <= 0xfaff) || // CJK compatibility ideographs
+        (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compatibility forms
+        (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth forms
+        (cp >= 0xffe0 && cp <= 0xffe6) || // Fullwidth signs
+        (cp >= 0x1f300 && cp <= 0x1f64f) || // emoji: symbols/pictographs, emoticons
+        (cp >= 0x1f680 && cp <= 0x1f6ff) || // transport/map symbols
+        (cp >= 0x1f900 && cp <= 0x1f9ff) || // supplemental symbols/pictographs
+        (cp >= 0x20000 && cp <= 0x3fffd) // CJK unified ideographs, supplementary planes
+    ) {
+        return 2;
+    }
+    return 1;
+}
+/** Total terminal display width of `text`, iterating by code point (not UTF-16 unit). */
+export function displayWidth(text) {
+    let width = 0;
+    for (const char of text) {
+        width += codePointWidth(char.codePointAt(0) ?? 0);
+    }
+    return width;
+}
+/** Right-pad `text` with spaces until its DISPLAY width reaches `target` (never cuts). */
+export function padEndDisplay(text, target) {
+    const pad = target - displayWidth(text);
+    return pad > 0 ? text + " ".repeat(pad) : text;
+}
+/**
+ * Cut `text` to `max` display columns, marking the cut with a single ellipsis
+ * character so a truncated path stays visually distinguishable from a real one.
+ */
+export function truncate(text, max) {
+    if (max <= 0) {
+        return "";
+    }
+    if (displayWidth(text) <= max) {
+        return text;
+    }
+    const budget = max - 1; // reserve one column for the ellipsis
+    let width = 0;
+    let result = "";
+    for (const char of text) {
+        const w = codePointWidth(char.codePointAt(0) ?? 0);
+        if (width + w > budget)
+            break;
+        result += char;
+        width += w;
+    }
+    return result + "…";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glm-coding-router",
-  "version": "1.1.2",
+  "version": "2.1.0",
   "description": "GLM Coding Plan workers for Claude Code and Codex",
   "type": "module",
   "license": "MIT",