glm-coding-router 1.1.2 → 2.1.0

package/dist/runs/registry.js

@@ -0,0 +1,350 @@
+import fs from "node:fs";
+import path from "node:path";
+import { createHash } from "node:crypto";
+import { logger, redact } from "../core/logging.js";
+import { activeRunFile, activeRunsDir, runDir, runsDir } from "../core/paths.js";
+import { atomicWriteFile } from "../project/atomic-write.js";
+import { ZAI_API_KEY_ENV } from "../core/zai-key.js";
+import { eventsFilePath } from "./store.js";
+/** C3: 120 chars is the widest a task title may ever be on disk or in a line. */
+export const TASK_TITLE_MAX_CHARS = 120;
+/**
+ * A heartbeat older than this (30 s = six missed 5 s ticks) plus a dead pid
+ * is what makes a run orphaned. The threshold is a property of the liveness
+ * protocol, not a user knob — tuning it without the heartbeat interval would
+ * silently break orphan detection.
+ */
+export const ORPHAN_HEARTBEAT_MS = 30_000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * C3: the first line of the prompt, redacted, cut to 120 chars — the only
+ * prompt-derived text ever persisted.
+ *
+ * `secrets` exists because the process environment is NOT where the key
+ * lives on the platform this ships to: `resolveZaiApiKey` reads it from the
+ * Windows User Environment (or a keychain) precisely so it stays out of
+ * `process.env`. A caller that already resolved the key passes it here; the
+ * env var is only a fallback for when it happens to be exported.
+ */
+export function taskTitleOf(prompt, secrets = []) {
+    const firstLine = prompt.split(/\r?\n/, 1)[0] ?? "";
+    return redact(firstLine, [...secrets, process.env[ZAI_API_KEY_ENV]]).slice(0, TASK_TITLE_MAX_CHARS);
+}
+/**
+ * C3: sha256 of the FULL prompt. The hash lets the estimator recognize the
+ * same task again while the body itself never touches disk.
+ */
+export function taskHashOf(prompt) {
+    return createHash("sha256").update(prompt, "utf8").digest("hex");
+}
+/**
+ * Registers a run and creates its history directory immediately — not at the
+ * end — so `watch` can attach to a run that is still going. Only this
+ * function propagates filesystem errors: a run whose registry entry cannot be
+ * written exists nowhere, and the caller must decide what to do about that.
+ */
+export function createRun(meta, deps) {
+    fs.mkdirSync(runDir(deps.home, meta.date, meta.id), { recursive: true });
+    fs.mkdirSync(activeRunsDir(deps.home), { recursive: true });
+    const active = {
+        ...meta,
+        state: "RUNNING",
+        heartbeatAt: (deps.now?.() ?? new Date()).toISOString(),
+    };
+    atomicWriteFile(activeRunFile(deps.home, meta.id), serialize(active));
+    return active;
+}
+/**
+ * Atomically patches the active file. Returns null — never throws — when the
+ * entry is missing or corrupt: a stale registry file must not take the run
+ * down with it, and callers (the heartbeat) treat null as "skip quietly".
+ */
+export function updateRun(home, id, patch) {
+    const file = activeRunFile(home, id);
+    try {
+        const current = readJsonFile(file);
+        if (!isStoredRun(current)) {
+            logger.debug(`updateRun: ${file} is missing or not a run entry`);
+            return null;
+        }
+        const next = { ...current, ...patch };
+        atomicWriteFile(file, serialize(next));
+        return next;
+    }
+    catch (error) {
+        logger.debug(`updateRun: patching ${id} failed: ${errorMessage(error)}`);
+        return null;
+    }
+}
+/**
+ * Writes `summary.json` into the run's history directory, then deletes the
+ * active file — that order is what makes "active file gone but no summary" a
+ * crash signature rather than a possible intermediate state of a clean run.
+ * Never throws: a run that already finished is not worth failing `finishRun`
+ * over, so every failure is logged at debug and skipped.
+ */
+export function finishRun(home, id, summary) {
+    const dir = locateRunDir(home, id);
+    if (dir === null) {
+        logger.debug(`finishRun: no history directory found for ${id}`);
+        return;
+    }
+    try {
+        atomicWriteFile(path.join(dir, "summary.json"), serialize(summary));
+    }
+    catch (error) {
+        logger.debug(`finishRun: writing summary for ${id} failed: ${errorMessage(error)}`);
+        return;
+    }
+    try {
+        fs.rmSync(activeRunFile(home, id), { force: true });
+    }
+    catch (error) {
+        logger.debug(`finishRun: removing active file for ${id} failed: ${errorMessage(error)}`);
+    }
+}
+/** Every registered run that claims to be alive, newest first. Corrupt files are skipped, never fatal. */
+export function listActive(home) {
+    const dir = activeRunsDir(home);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const runs = [];
+    for (const name of names) {
+        if (!name.endsWith(".json")) {
+            continue;
+        }
+        const entry = readJsonFile(path.join(dir, name));
+        if (isStoredRun(entry)) {
+            runs.push(entry);
+        }
+        else {
+            logger.debug(`listActive: skipping unreadable entry ${name}`);
+        }
+    }
+    // ULIDs sort chronologically, so id order is start order with no parsing.
+    return runs.sort((a, b) => (a.id < b.id ? 1 : -1));
+}
+/** History entries, newest first, optionally filtered by kind and/or terminal state. */
+export function listHistory(home, filter = {}) {
+    const refs = [];
+    for (const date of historyDates(home)) {
+        for (const id of runIdsIn(path.join(historyRoot(home), date))) {
+            const ref = readSummaryRef(home, date, id);
+            if (ref !== null &&
+                (filter.kind === undefined || ref.kind === filter.kind) &&
+                (filter.state === undefined || ref.state === filter.state)) {
+                refs.push(ref);
+            }
+        }
+    }
+    // Dates and ids were read sorted ascending; reverse for newest-first.
+    return refs.reverse();
+}
+/**
+ * Enforces `retentionDays` then `maxRuns` (oldest first), called
+ * opportunistically — a pruning failure must never block the work around it.
+ * Returns the removed run ids so `runs clean` can say what it did.
+ */
+export function pruneHistory(home, limits) {
+    const now = Date.now();
+    const entries = [];
+    for (const date of historyDates(home)) {
+        const dateMs = Date.parse(`${date}T00:00:00.000Z`);
+        if (!Number.isFinite(dateMs)) {
+            logger.debug(`pruneHistory: skipping non-date directory ${date}`);
+            continue;
+        }
+        for (const id of runIdsIn(path.join(historyRoot(home), date))) {
+            entries.push({ date, id, dateMs });
+        }
+    }
+    const expired = entries.filter((entry) => now - entry.dateMs >= limits.retentionDays * DAY_MS);
+    const kept = entries
+        .filter((entry) => !expired.includes(entry))
+        .sort((a, b) => (a.date === b.date ? (a.id < b.id ? -1 : 1) : a.date < b.date ? -1 : 1));
+    // Oldest first, only as many as exceed the cap.
+    const overflow = kept.slice(0, Math.max(0, kept.length - limits.maxRuns));
+    const removed = [];
+    const touchedDates = new Set();
+    for (const entry of [...expired, ...overflow]) {
+        try {
+            fs.rmSync(runDir(home, entry.date, entry.id), { recursive: true, force: true });
+            removed.push(entry.id);
+            touchedDates.add(entry.date);
+        }
+        catch (error) {
+            logger.debug(`pruneHistory: removing ${entry.id} failed: ${errorMessage(error)}`);
+        }
+    }
+    for (const date of touchedDates) {
+        try {
+            fs.rmdirSync(path.join(historyRoot(home), date));
+        }
+        catch {
+            // Directory not empty (a kept/failed removal lives there) — nothing to do.
+        }
+    }
+    return { removed };
+}
+/**
+ * True when the heartbeat is stale AND the process is gone. Both conditions:
+ * a fresh heartbeat with a dead pid is a run that just hasn't ticked again,
+ * and a stale heartbeat with a live pid is a busy worker, not an orphan.
+ */
+export function isOrphaned(run, deps = {}) {
+    const now = deps.now?.() ?? Date.now();
+    const heartbeatAge = now - Date.parse(run.heartbeatAt);
+    // A NaN age (unparseable heartbeatAt) fails the comparison, so a corrupt
+    // entry is treated as fresh rather than reaped on a technicality.
+    if (!(heartbeatAge > ORPHAN_HEARTBEAT_MS)) {
+        return false;
+    }
+    const isAlive = deps.isAlive ?? defaultIsAlive;
+    return !isAlive(run.pid);
+}
+/**
+ * The liveness probe: `process.kill(pid, 0)` sends no signal, it only asks
+ * the OS whether the process exists. EPERM means it exists but belongs to
+ * someone else — that is a live pid, not a dead one.
+ */
+function defaultIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+function historyRoot(home) {
+    return path.join(runsDir(home), "history");
+}
+/** Date directories, sorted oldest first so consumers can rely on iteration order. */
+function historyDates(home) {
+    try {
+        return fs
+            .readdirSync(historyRoot(home), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+function runIdsIn(dir) {
+    try {
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Builds one history entry. `summary.json` answers "how did it end"; when it
+ * is missing the run crashed, and kind/startedAt come from the first line of
+ * `events.jsonl` (a `RunStarted`, written before anything could crash).
+ */
+function readSummaryRef(home, date, id) {
+    const dir = runDir(home, date, id);
+    const summary = readJsonFile(path.join(dir, "summary.json"));
+    const firstEvent = readFirstEvent(dir);
+    if (!isSummary(summary) && firstEvent === null) {
+        // Neither artifact is readable — debris, not a run worth listing.
+        logger.debug(`listHistory: skipping ${dir} (no readable summary or events)`);
+        return null;
+    }
+    const state = isSummary(summary) ? summary.state : "CRASHED";
+    return {
+        id,
+        date,
+        kind: firstEvent?.kind ?? null,
+        state,
+        startedAt: firstEvent?.startedAt ?? null,
+        summary: isSummary(summary) ? summary : null,
+    };
+}
+/** The first line of `events.jsonl`, or null — reading more would make a listing O(stream). */
+function readFirstEvent(dir) {
+    try {
+        const firstLine = fs.readFileSync(eventsFilePath(dir), "utf8").split(/\r?\n/, 1)[0] ?? "";
+        if (firstLine.trim() === "") {
+            return null;
+        }
+        const parsed = JSON.parse(firstLine);
+        if (typeof parsed !== "object" || parsed === null) {
+            return null;
+        }
+        const record = parsed;
+        if (typeof record.ts !== "string") {
+            return null;
+        }
+        return {
+            kind: typeof record.kind === "string" ? record.kind : null,
+            startedAt: record.ts,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Where a run's history directory is. The active file is the fast path; the
+ * scan exists so `finishRun` still works when the active file was already
+ * reaped (crashed process, later cleanup).
+ */
+function locateRunDir(home, id) {
+    const entry = readJsonFile(activeRunFile(home, id));
+    if (isStoredRun(entry)) {
+        const dir = runDir(home, entry.date, id);
+        if (fs.existsSync(dir)) {
+            return dir;
+        }
+    }
+    for (const date of historyDates(home)) {
+        const dir = runDir(home, date, id);
+        if (fs.existsSync(dir)) {
+            return dir;
+        }
+    }
+    return null;
+}
+function readJsonFile(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Deliberately shallow: enough to know the file is a run entry, not a full
+ * schema check — a future field must not make every old entry unreadable.
+ */
+function isStoredRun(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    return (typeof record.id === "string" &&
+        typeof record.state === "string" &&
+        typeof record.heartbeatAt === "string");
+}
+function isSummary(value) {
+    return typeof value === "object" && value !== null && typeof value.state === "string";
+}
+function serialize(value) {
+    return JSON.stringify(value, null, 2) + "\n";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/runs/store.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "../core/logging.js";
+/** The one file every run is guaranteed to leave behind, even when it crashed. */
+export const EVENTS_FILE_NAME = "events.jsonl";
+/** `events.jsonl` inside a run directory; exported so every module spells the path the same way. */
+export function eventsFilePath(runDirPath) {
+    return path.join(runDirPath, EVENTS_FILE_NAME);
+}
+/**
+ * Opens `events.jsonl` in append mode. Append mode is the whole crash story:
+ * the file is never truncated, every line reaches the OS as it is appended,
+ * and a killed process leaves at worst one half-written final line — which
+ * `readEvents` tolerates — and never a summary, which is precisely how
+ * `runs show` tells a crashed run from a finished one.
+ *
+ * `append` may throw (disk full, fd gone); the event bus catches subscriber
+ * exceptions, so a broken store degrades to lost lines instead of a dead run.
+ */
+export function openRunStore(runDirPath) {
+    fs.mkdirSync(runDirPath, { recursive: true });
+    const file = eventsFilePath(runDirPath);
+    const fd = fs.openSync(file, "a");
+    let closed = false;
+    return {
+        path: file,
+        append(event) {
+            if (closed) {
+                logger.debug(`run store: append after close on ${file} skipped`);
+                return;
+            }
+            fs.writeSync(fd, JSON.stringify(event) + "\n", null, "utf8");
+        },
+        flush() {
+            if (!closed) {
+                fs.fsyncSync(fd);
+            }
+        },
+        close() {
+            if (closed) {
+                return;
+            }
+            closed = true;
+            try {
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+        },
+    };
+}
+/**
+ * Reconstructs the event stream from a run directory. A malformed line is
+ * skipped, not fatal — a truncated final line is the normal wreckage of a
+ * crash, and the events before it are exactly what survived. A missing file
+ * yields an empty stream for the same reason: history readers must never
+ * throw on the artifacts a crash leaves behind.
+ */
+export function readEvents(runDirPath) {
+    let text;
+    try {
+        text = fs.readFileSync(eventsFilePath(runDirPath), "utf8");
+    }
+    catch {
+        logger.debug(`run store: no events file in ${runDirPath}`);
+        return [];
+    }
+    const events = [];
+    const lines = text.split(/\r?\n/);
+    for (const [index, line] of lines.entries()) {
+        if (line.trim() === "") {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(line);
+            if (isEventLike(parsed)) {
+                events.push(parsed);
+            }
+            else {
+                logger.debug(`run store: line ${index + 1} in ${runDirPath} is not an event`);
+            }
+        }
+        catch {
+            logger.debug(`run store: skipping malformed line ${index + 1} in ${runDirPath}`);
+        }
+    }
+    return events;
+}
+/**
+ * Rebuilds a summary from events alone. The stream's `RunCompleted` numbers
+ * (A0: taken straight from the result message) are authoritative when
+ * present; the event-derived fallbacks exist so a crashed run still gets a
+ * meaningful summary — that is the entire point of rebuilding rather than
+ * trusting a file the crash prevented us from writing.
+ */
+export function summarize(events) {
+    let state = "CRASHED";
+    let turns = 0;
+    let resultTurns = 0;
+    let resultDurationMs = 0;
+    let durationMs = 0;
+    let tokensIn = 0;
+    let tokensOut = 0;
+    let denied = 0;
+    let retries = 0;
+    let validation = "none";
+    const filesChanged = new Set();
+    for (const event of events) {
+        switch (event.type) {
+            case "TurnStarted":
+                turns = Math.max(turns, event.turn);
+                break;
+            case "FileChanged":
+                filesChanged.add(event.path);
+                break;
+            case "ToolDenied":
+                denied += 1;
+                if (validation === "pending") {
+                    validation = "denied";
+                }
+                break;
+            case "ApiRetry":
+                retries += 1;
+                break;
+            case "ValidationStarted":
+                validation = "pending";
+                break;
+            case "ValidationCompleted":
+                validation = event.ok ? "ok" : "failed";
+                break;
+            case "RunCompleted":
+                state = "COMPLETED";
+                // A run can carry MORE THAN ONE result message: a child that hits
+                // --max-turns and continues emits one per segment. Observed live on
+                // 2026-09-20 — RunFailed(max_turns), then two RunCompleted — where
+                // overwriting made a 21-minute, 64-turn run persist as "88s, 5 turns".
+                // Each result describes only its own segment, so accumulate, and let
+                // the derived turn count win when it is larger.
+                resultTurns += event.turns;
+                resultDurationMs += event.durationMs;
+                tokensIn += event.tokensIn;
+                tokensOut += event.tokensOut;
+                break;
+            case "RunFailed":
+                state = "FAILED";
+                break;
+            case "RunCancelled":
+                state = "CANCELLED";
+                break;
+            default:
+                break;
+        }
+    }
+    // The wall clock is the span of the stream; a sum of per-segment result
+    // durations misses the gaps between them. Take whichever is larger so a
+    // long run can never be reported as a short one.
+    const span = events.length > 0
+        ? Date.parse(events[events.length - 1].ts) - Date.parse(events[0].ts)
+        : 0;
+    durationMs = Math.max(resultDurationMs, Number.isFinite(span) && span > 0 ? span : 0);
+    turns = Math.max(turns, resultTurns);
+    return {
+        id: events.length > 0 ? events[0].runId : "",
+        state,
+        turns,
+        durationMs,
+        filesChanged: [...filesChanged],
+        tokensIn,
+        tokensOut,
+        denied,
+        retries,
+        validation,
+    };
+}
+/**
+ * The runtime check is deliberately just "parses and has a `type` string":
+ * fully validating the union at runtime would duplicate the event model, and
+ * a line that passes this check but carries wrong fields is history written
+ * by a future version — dropping it would lose data forever.
+ */
+function isEventLike(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.type === "string");
+}

package/dist/runs/ulid.js

@@ -0,0 +1,112 @@
+import { randomBytes } from "node:crypto";
+/**
+ * ULID generation (specs/v2-architecture.md, Phase B).
+ *
+ * Lexicographic sort order equals chronological order — that property, not
+ * the id's shape, is why runs use ULIDs instead of UUIDs: the run history is
+ * browsed by sorting ids as plain strings.
+ */
+/** Crockford base32: no I, L, O or U, so no visually ambiguous character ever appears in a run id. */
+const ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+const TIME_LEN = 10;
+const RANDOM_BYTES = 10; // 80 bits = exactly 16 base32 chars × 5 bits
+/**
+ * Process-wide monotonic state: the last timestamp used and the random
+ * component it was paired with. Two ids in the same millisecond must still
+ * order, so the second one increments the first one's randomness instead of
+ * drawing fresh bytes.
+ */
+let lastTime = -1;
+let lastRandom = null;
+/**
+ * A 26-char ULID: 10 chars of millisecond timestamp (most significant first)
+ * followed by 16 chars of randomness. Monotonic within the process — same-ms
+ * calls increment the 80-bit random component as a big-endian integer, so
+ * generated ids never collide and always sort after their predecessors.
+ * `now` is injectable so tests can pin and freeze time.
+ */
+export function ulid(now = Date.now) {
+    let time = now();
+    let random = null;
+    // `<=` rather than `===` also absorbs a clock that jumps backwards: reusing
+    // the last timestamp with an incremented random part preserves the invariant
+    // that actually matters — generation order == sort order.
+    if (lastRandom !== null && time <= lastTime) {
+        random = incrementRandom(lastRandom);
+        if (random === null) {
+            // All 80 random bits overflowed (probability 2^-80). Spin to the next
+            // millisecond rather than return a value that sorts before its
+            // predecessor; if the clock never advances (a frozen injected clock),
+            // step the timestamp ourselves — still strictly after the previous id.
+            let spins = 0;
+            do {
+                time = now();
+            } while (time <= lastTime && ++spins < 1_000_000);
+            if (time <= lastTime) {
+                time = lastTime + 1;
+            }
+            random = randomBytes(RANDOM_BYTES);
+        }
+        else {
+            time = lastTime;
+        }
+    }
+    else {
+        random = randomBytes(RANDOM_BYTES);
+    }
+    lastTime = time;
+    lastRandom = random;
+    return encodeTime(time) + encodeRandom(random);
+}
+/** `run_` + a ULID (doc §5): the prefix makes run ids self-describing in logs, dirs and file names. */
+export function runId(now = Date.now) {
+    return `run_${ulid(now)}`;
+}
+/**
+ * A 48-bit millisecond timestamp fits exactly in a double, so plain division
+ * encodes it most-significant-first into 10 chars — which is what makes the
+ * time part of the string sort chronologically.
+ */
+function encodeTime(time) {
+    let chars = "";
+    let remaining = time;
+    for (let count = 0; count < TIME_LEN; count++) {
+        chars = ENCODING[remaining % 32] + chars;
+        remaining = Math.floor(remaining / 32);
+    }
+    return chars;
+}
+/**
+ * 10 bytes → 16 × 5-bit symbols, big-endian. 80 is a multiple of 5, so the
+ * bit funnel drains exactly with nothing left over.
+ */
+function encodeRandom(bytes) {
+    let chars = "";
+    let buffer = 0;
+    let bits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            chars += ENCODING[(buffer >>> bits) & 31];
+        }
+    }
+    return chars;
+}
+/**
+ * +1 on the 80-bit random component read as a big-endian integer. Returns
+ * null when every bit was already 1 — the caller must then move to a new
+ * millisecond, because a wrapped value would sort before its predecessor.
+ */
+function incrementRandom(bytes) {
+    const next = Uint8Array.from(bytes);
+    for (let index = next.length - 1; index >= 0; index--) {
+        if (next[index] < 0xff) {
+            next[index] += 1;
+            return next;
+        }
+        next[index] = 0;
+    }
+    return null;
+}