glm-coding-router 1.1.1 → 2.0.0

package/dist/templates/claude-block.js

@@ -46,4 +46,13 @@ After worker completion:
 4. resolve integration problems
 5. accept only after verification
 
+Worker exit codes 41 and 42 are NOT crashes:
+
+- stdout carries one JSON object: \`{"status":"handoff_required", ...}\`
+- read \`handoff_path\` — a handoff.md with what was done, what remains, files
+  changed, and untracked files that are NOT in diff.patch
+- continue the task yourself in the SAME worktree, starting from "Remaining"
+- do not re-run the worker until quota resets
+- 41 means nothing was spawned; 42 means work was done and is preserved
+
 <!-- glm-coding-router:end -->`;

package/dist/templates/glm-delegation-skill.js

@@ -1,68 +1,79 @@
 /** Codex skill definition (spec §26). Keep in sync with the spec. */
 export const GLM_DELEGATION_SKILL_NAME = "glm-delegation";
-export const GLM_DELEGATION_SKILL_MD = `---
-name: glm-delegation
-description: >
-  Delegate well-scoped implementation, testing,
-  repository exploration, boilerplate, CRUD,
-  documentation, and mechanical refactoring to
-  GLM Coding Plan workers.
----
-
-# GLM Delegation
-
-Available commands:
-
-glm-worker "<task>"
-glm-review "<task>"
-
-## Use glm-review for
-
-- repository exploration
-- dependency analysis
-- locating implementations
-- call-chain discovery
-- code review
-
-## Use glm-worker for
-
-- CRUD
-- unit tests
-- implementation
-- documentation
-- repetitive changes
-- mechanical refactoring
-
-## Keep in primary Codex agent
-
-- requirements
-- architecture
-- ambiguous rules
-- security-sensitive design
-- difficult debugging
-- integration
-- final acceptance
-
-## Delegation packet
-
-Always provide:
-
-TASK
-SCOPE
-ALLOWED FILES
-FORBIDDEN FILES
-REQUIREMENTS
-CONSTRAINTS
-ACCEPTANCE CRITERIA
-VALIDATION
-EXPECTED OUTPUT
-
-## Verification
-
-After GLM finishes:
-
-- inspect the actual diff
-- independently run relevant validation
-- compare implementation with requirements
-- reject or correct worker output when needed
+export const GLM_DELEGATION_SKILL_MD = `---
+name: glm-delegation
+description: >
+  Delegate well-scoped implementation, testing,
+  repository exploration, boilerplate, CRUD,
+  documentation, and mechanical refactoring to
+  GLM Coding Plan workers.
+---
+
+# GLM Delegation
+
+Available commands:
+
+glm-worker "<task>"
+glm-review "<task>"
+
+## Use glm-review for
+
+- repository exploration
+- dependency analysis
+- locating implementations
+- call-chain discovery
+- code review
+
+## Use glm-worker for
+
+- CRUD
+- unit tests
+- implementation
+- documentation
+- repetitive changes
+- mechanical refactoring
+
+## Keep in primary Codex agent
+
+- requirements
+- architecture
+- ambiguous rules
+- security-sensitive design
+- difficult debugging
+- integration
+- final acceptance
+
+## Delegation packet
+
+Always provide:
+
+TASK
+SCOPE
+ALLOWED FILES
+FORBIDDEN FILES
+REQUIREMENTS
+CONSTRAINTS
+ACCEPTANCE CRITERIA
+VALIDATION
+EXPECTED OUTPUT
+
+## Verification
+
+After GLM finishes:
+
+- inspect the actual diff
+- independently run relevant validation
+- compare implementation with requirements
+- reject or correct worker output when needed
+
+## Exit codes 41 and 42 are not crashes
+
+A worker may stop because the GLM quota ran low rather than because it broke.
+
+- stdout carries one JSON object: \`{"status":"handoff_required", ...}\`
+- read \`handoff_path\` — a handoff.md with what was done, what remains, files
+  changed, and untracked files that are NOT in diff.patch
+- continue the task yourself in the SAME worktree, starting from "Remaining"
+- do not re-run the worker until quota resets
+- 41 means nothing was spawned; 42 means work was done and is preserved
 `;

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,78 @@
+/**
+ * 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 color = opts?.color ?? (isTTY && !noColor);
+    return {
+        write(text) {
+            stream.write(text);
+        },
+        line(text) {
+            stream.write((text ?? "") + "\n");
+        },
+        isTTY,
+        color,
+        columns: terminal.columns ?? 80,
+    };
+}
+/**
+ * Cut `text` to `max` characters, 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 (text.length <= max) {
+        return text;
+    }
+    return text.slice(0, max - 1) + "…";
+}

package/package.json

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