glm-coding-router 1.1.1 → 2.0.0

package/dist/runs/drain.js

@@ -0,0 +1,165 @@
+import { execFile } from "node:child_process";
+import { logger } from "../core/logging.js";
+import { zoneFor } from "../budget/manager.js";
+import { usableBudgetOf } from "../routing/glm-routing.js";
+/**
+ * Grace between SIGINT and SIGTERM. Five seconds is enough for `claude` to
+ * finish flushing the tool result it is holding and exit on its own — the
+ * point of the ladder is to let it close cleanly, not to win a race.
+ */
+export const TERMINATE_GRACE_MS = 5_000;
+/** Second grace, before Windows' last resort. Short: by now it has ignored two signals. */
+export const TASKKILL_GRACE_MS = 2_000;
+/** Worst-to-best, so "at or below HANDOFF_READY" is one comparison. */
+const ZONE_SEVERITY = {
+    CRITICAL: 3,
+    HANDOFF_READY: 2,
+    CONSERVE: 1,
+    HEALTHY: 0,
+};
+/**
+ * Should this run be worried yet? (specs/v2-architecture.md Phase F.)
+ *
+ * Pure: the caller does the polling and owns every side effect. Note what this
+ * projects — the cost of what is LEFT, not of the whole task. A run three
+ * quarters done needs a quarter of the estimate, and treating it as if it were
+ * starting over would raise the alarm on every long run that is nearly
+ * finished, which is precisely when interrupting costs the most.
+ *
+ * `confidence: "unknown"` can never reach `atRisk`, because `zoneFor` fails
+ * open to HEALTHY — a monitoring outage must not drain a live child.
+ */
+export function assessDrain(input) {
+    const routing = input.config.routing;
+    const zone = zoneFor(input.snapshot, routing);
+    const usableBudget = usableBudgetOf(input.snapshot, routing.reserveRatio);
+    // A run that has already used every turn it was given has nothing left to
+    // project; an unknown/zero ceiling means "assume it all still lies ahead".
+    const remainingTurnRatio = input.maxTurns > 0
+        ? Math.min(1, Math.max(0, (input.maxTurns - input.turnsDone) / input.maxTurns))
+        : 1;
+    const projectedCost = input.estimate.p90 * routing.safetyFactor * remainingTurnRatio;
+    return {
+        zone,
+        usableBudget,
+        projectedCost,
+        atRisk: ZONE_SEVERITY[zone] >= ZONE_SEVERITY.HANDOFF_READY && projectedCost > usableBudget,
+    };
+}
+/**
+ * Polls the budget while the child runs and calls back the first time the run
+ * becomes at-risk, then never again: the warning and the checkpoint are worth
+ * writing once, and a per-poll repeat would turn a tight quota into a wall of
+ * identical stderr lines.
+ *
+ * Every timer is injectable because a test must not wait a real minute, and
+ * the interval is unref'd so a poll in flight can never hold the process open
+ * past the run it was watching.
+ */
+export function startDrainWatch(input) {
+    const setIntervalFn = input.setIntervalImpl ?? ((tick, ms) => setInterval(tick, ms));
+    const clearIntervalFn = input.clearIntervalImpl ?? ((handle) => clearInterval(handle));
+    let fired = false;
+    let stopped = false;
+    const tick = () => {
+        if (fired || stopped) {
+            return;
+        }
+        // Fire-and-forget: a poll that rejects must not become an unhandled
+        // rejection, and a slow endpoint must not delay the next tick.
+        void (async () => {
+            try {
+                const assessment = assessDrain({
+                    snapshot: await input.readBudget(),
+                    estimate: input.estimate(),
+                    config: input.config,
+                    turnsDone: input.turnsDone(),
+                    maxTurns: input.maxTurns,
+                });
+                if (assessment.atRisk && !fired && !stopped) {
+                    fired = true;
+                    input.onAtRisk(assessment);
+                }
+            }
+            catch (error) {
+                logger.debug(`drain watch: poll failed, continuing: ${errorMessage(error)}`);
+            }
+        })();
+    };
+    const handle = setIntervalFn(tick, Math.max(1, input.config.routing.pollIntervalSec) * 1000);
+    handle.unref?.();
+    return {
+        stop() {
+            stopped = true;
+            clearIntervalFn(handle);
+        },
+    };
+}
+/**
+ * Stop the child at a safe boundary: SIGINT, grace, SIGTERM, and on Windows
+ * `taskkill /pid <pid> /t` as the last resort — the same ladder and the same
+ * no-shell rule the spawn helpers already follow.
+ *
+ * Windows has no real POSIX signals: Node emulates `kill` by terminating the
+ * process, and a `claude` that spawned its own children leaves them behind,
+ * which is what `/t` (kill the tree) is for. `/f` is deliberately NOT used
+ * before the tree walk — a forced kill is the thing this whole ladder exists
+ * to avoid, because it is what loses the work on disk.
+ *
+ * Resolves when the child is gone or the ladder is exhausted; never throws.
+ */
+export async function terminateChild(child, options = {}) {
+    const platform = options.platform ?? process.platform;
+    const wait = options.waitImpl ?? defaultWait;
+    const exited = () => child.exitCode !== null || child.signalCode !== null;
+    send(child, "SIGINT");
+    if (exited()) {
+        return;
+    }
+    await wait(options.graceMs ?? TERMINATE_GRACE_MS);
+    if (exited()) {
+        return;
+    }
+    send(child, "SIGTERM");
+    if (platform !== "win32") {
+        return;
+    }
+    await wait(options.taskkillGraceMs ?? TASKKILL_GRACE_MS);
+    if (exited() || typeof child.pid !== "number") {
+        return;
+    }
+    const taskkill = options.runTaskkill ?? defaultTaskkill;
+    try {
+        taskkill(child.pid);
+    }
+    catch (error) {
+        logger.debug(`terminateChild: taskkill failed: ${errorMessage(error)}`);
+    }
+}
+/** A kill on an already-dead child throws ESRCH; that is success, not an error. */
+function send(child, signal) {
+    try {
+        child.kill(signal);
+    }
+    catch (error) {
+        logger.debug(`terminateChild: ${signal} failed: ${errorMessage(error)}`);
+    }
+}
+/** argv array, no shell — the same rule every spawn in this package follows. */
+function defaultTaskkill(pid) {
+    execFile("taskkill", ["/pid", String(pid), "/t"], { windowsHide: true }, (error) => {
+        if (error) {
+            logger.debug(`taskkill /pid ${pid} /t failed: ${error.message}`);
+        }
+    });
+}
+function defaultWait(ms) {
+    return new Promise((resolve) => {
+        // unref: a pending grace period must never keep the process alive.
+        const timer = setTimeout(resolve, ms);
+        timer.unref?.();
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/runs/heartbeat.js

@@ -0,0 +1,45 @@
+import { logger } from "../core/logging.js";
+import { updateRun } from "./registry.js";
+/**
+ * Doc §6 fixes the tick at 5 s and keeps it out of config on purpose: the
+ * 30 s orphan threshold is six missed ticks of THIS interval. A config knob
+ * here would let anyone silently break liveness detection.
+ */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
+/**
+ * Emits a `Heartbeat` event and refreshes `heartbeatAt` in the active file on
+ * every tick — the pair that `watch` and orphan detection read. A file
+ * failure is caught and logged at debug: the heartbeat is liveness plumbing,
+ * and plumbing must never kill the run it is monitoring. The bus's own
+ * subscriber guard covers the emit side.
+ */
+export function startHeartbeat(deps) {
+    const intervalMs = deps.intervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS;
+    const tick = () => {
+        deps.bus.emit({ type: "Heartbeat", state: deps.getState(), turn: deps.getTurn() });
+        try {
+            updateRun(deps.home, deps.runId, { heartbeatAt: new Date().toISOString() });
+        }
+        catch (error) {
+            logger.debug(`heartbeat: could not refresh ${deps.runId}: ${errorMessage(error)}`);
+        }
+    };
+    const setIntervalImpl = deps.setIntervalImpl ?? ((fn, ms) => setInterval(fn, ms));
+    const clearIntervalImpl = deps.clearIntervalImpl ?? ((timer) => clearInterval(timer));
+    let timer = setIntervalImpl(tick, intervalMs);
+    // Unref when the runtime supports it: a leaked heartbeat timer must never
+    // be the reason the process stays open after the run finished.
+    timer.unref?.();
+    return {
+        stop() {
+            if (timer === null) {
+                return;
+            }
+            clearIntervalImpl(timer);
+            timer = null;
+        },
+    };
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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);
+}