@indigoai-us/hq-cli 5.126.0 → 5.127.0

package/dist/lib/lanes/quota.js

@@ -0,0 +1,320 @@
+/**
+ * Machine-written provider quota, keyed by account and model.
+ *
+ * `enabled` and `disabled_reason` live in personal/lanes/config.json and are
+ * the operator's hand-written switch. `quota_reset_at` and `needs_credits`
+ * are written here, in personal/lanes/quota.json, from the provider's own
+ * 429. They are separate fields because a quota hold expires on its own:
+ * copying it into `disabled_reason` or flipping `enabled` would erase the
+ * operator's reason, and would leave the account switched off after the
+ * provider reset. The balancer reads this file and does not rewrite the
+ * operator fields.
+ *
+ * A weekly-limit 429 names a reset and applies to every model on that
+ * account (measured: account b, every model, until the reset). A credits
+ * 429 names one model and no reset (measured: account d refuses
+ * claude-fable-5-1 and still runs claude-opus-5). The record is therefore
+ * per (account, model), plus an account-wide reset when the text is a
+ * usage limit rather than a switch-model refusal.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+export const QUOTA_STATE_REL = path.join("personal", "lanes", "quota.json");
+export const QUOTA_SCHEMA_VERSION = "hq-lanes-quota.v1";
+const MONTHS = {
+    jan: 0,
+    feb: 1,
+    mar: 2,
+    apr: 3,
+    may: 4,
+    jun: 5,
+    jul: 6,
+    aug: 7,
+    sep: 8,
+    oct: 9,
+    nov: 10,
+    dec: 11,
+};
+function emptyState() {
+    return { schema_version: QUOTA_SCHEMA_VERSION, providers: {} };
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function quotaStatePath(hqRoot) {
+    return path.join(hqRoot, QUOTA_STATE_REL);
+}
+export function loadQuotaState(hqRoot) {
+    const filePath = quotaStatePath(hqRoot);
+    let text;
+    try {
+        text = fs.readFileSync(filePath, "utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return emptyState();
+        throw err;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return emptyState();
+    }
+    if (!isPlainObject(parsed))
+        return emptyState();
+    const providers = {};
+    const rawProviders = isPlainObject(parsed.providers) ? parsed.providers : {};
+    for (const provider of ["claude", "codex", "grok"]) {
+        const rawAccounts = rawProviders[provider];
+        if (!isPlainObject(rawAccounts))
+            continue;
+        const accounts = {};
+        for (const [id, raw] of Object.entries(rawAccounts)) {
+            if (!isPlainObject(raw))
+                continue;
+            const models = {};
+            if (isPlainObject(raw.models)) {
+                for (const [model, entry] of Object.entries(raw.models)) {
+                    if (!isPlainObject(entry))
+                        continue;
+                    const quota = {};
+                    if (typeof entry.quota_reset_at === "string" && entry.quota_reset_at.length > 0) {
+                        quota.quota_reset_at = entry.quota_reset_at;
+                    }
+                    if (entry.needs_credits === true)
+                        quota.needs_credits = true;
+                    if (typeof entry.marker === "string" && entry.marker.length > 0) {
+                        quota.marker = entry.marker;
+                    }
+                    if (quota.quota_reset_at || quota.needs_credits || quota.marker) {
+                        models[model] = quota;
+                    }
+                }
+            }
+            const account = { models };
+            if (typeof raw.all_models_quota_reset_at === "string" &&
+                raw.all_models_quota_reset_at.length > 0) {
+                account.all_models_quota_reset_at = raw.all_models_quota_reset_at;
+            }
+            accounts[id] = account;
+        }
+        providers[provider] = accounts;
+    }
+    return { schema_version: QUOTA_SCHEMA_VERSION, providers };
+}
+function writeQuotaState(hqRoot, state) {
+    const filePath = quotaStatePath(hqRoot);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(state, null, 2)}\n`, "utf8");
+    fs.renameSync(tmp, filePath);
+}
+/**
+ * Parse "resets Sep 24, 2am (UTC)" into an ISO timestamp. The year is the
+ * current UTC year, rolled forward when that instant is already past.
+ * Returns null when the text names no reset.
+ */
+export function parseProviderResetTime(text, now) {
+    const match = /resets\s+([A-Za-z]+)\s+(\d{1,2})(?:,\s*(\d{1,2})(?::(\d{2}))?\s*(am|pm))?(?:\s*\(UTC\))?/i.exec(text);
+    if (!match)
+        return null;
+    const month = MONTHS[(match[1] ?? "").slice(0, 3).toLowerCase()];
+    if (month === undefined)
+        return null;
+    const day = Number(match[2]);
+    if (!Number.isInteger(day) || day < 1 || day > 31)
+        return null;
+    let hour = 0;
+    let minute = 0;
+    if (match[3] !== undefined) {
+        hour = Number(match[3]);
+        minute = match[4] !== undefined ? Number(match[4]) : 0;
+        const ap = (match[5] ?? "").toLowerCase();
+        if (ap === "pm" && hour < 12)
+            hour += 12;
+        if (ap === "am" && hour === 12)
+            hour = 0;
+        if (hour > 23 || minute > 59)
+            return null;
+    }
+    let year = now.getUTCFullYear();
+    let ts = Date.UTC(year, month, day, hour, minute, 0, 0);
+    if (ts < now.getTime() - 36 * 60 * 60 * 1000) {
+        year += 1;
+        ts = Date.UTC(year, month, day, hour, minute, 0, 0);
+    }
+    return new Date(ts).toISOString();
+}
+function isCreditsRefusal(text) {
+    return /requires usage credits/i.test(text) || /switch to another model/i.test(text);
+}
+function isUsageLimitShape(text) {
+    return /weekly limit|usage limit|rate limit|quota|usage credits|hit your .+ limit/i.test(text);
+}
+/**
+ * Read only `api_error_status`, `is_error`, and `result` off the last
+ * `type: "result"` object. Nothing else from the payload is returned, and
+ * this function does not log.
+ */
+export function quotaFieldsFromOutput(text) {
+    const lines = text.split("\n");
+    for (let i = lines.length - 1; i >= 0; i -= 1) {
+        const line = (lines[i] ?? "").trim();
+        if (!line.startsWith("{"))
+            continue;
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        if (!isPlainObject(parsed) || parsed.type !== "result")
+            continue;
+        return {
+            api_error_status: parsed.api_error_status,
+            is_error: parsed.is_error,
+            result: parsed.result,
+        };
+    }
+    return null;
+}
+export function quotaSignalFromFields(fields, model, now) {
+    const text = typeof fields.result === "string" ? fields.result : "";
+    const is429 = fields.api_error_status === 429;
+    const usageShaped = fields.is_error === true && isUsageLimitShape(text);
+    if (!is429 && !usageShaped)
+        return null;
+    if (isCreditsRefusal(text) && !/resets\s+/i.test(text)) {
+        const marker = model ? `needs credits for ${model}` : "needs credits";
+        return {
+            reason: "account_model_unavailable",
+            model,
+            needs_credits: true,
+            marker,
+        };
+    }
+    const quota_reset_at = text.length > 0 ? parseProviderResetTime(text, now) ?? undefined : undefined;
+    return {
+        reason: "account_quota_exhausted",
+        quota_reset_at,
+        model,
+        account_wide: true,
+    };
+}
+export function readQuotaSignal(runDir, model, now, workerOutOffset = 0) {
+    const outPath = path.join(runDir, "logs", "worker.out");
+    let text;
+    try {
+        const bytes = fs.readFileSync(outPath);
+        text = bytes.subarray(Math.min(workerOutOffset, bytes.length)).toString("utf8");
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const fields = quotaFieldsFromOutput(text);
+    if (!fields)
+        return null;
+    return quotaSignalFromFields(fields, model, now);
+}
+export function recordAccountQuota(hqRoot, provider, accountId, signal) {
+    const state = loadQuotaState(hqRoot);
+    const accounts = state.providers[provider] ?? {};
+    const current = accounts[accountId] ?? { models: {} };
+    const models = { ...current.models };
+    if (signal.model) {
+        const prior = models[signal.model] ?? {};
+        const next = { ...prior };
+        if (signal.needs_credits) {
+            next.needs_credits = true;
+            next.marker = signal.marker ?? `needs credits for ${signal.model}`;
+            delete next.quota_reset_at;
+        }
+        if (signal.quota_reset_at && !signal.needs_credits) {
+            next.quota_reset_at = signal.quota_reset_at;
+        }
+        models[signal.model] = next;
+    }
+    const account = { ...current, models };
+    if (signal.account_wide && signal.quota_reset_at) {
+        account.all_models_quota_reset_at = signal.quota_reset_at;
+    }
+    accounts[accountId] = account;
+    state.providers[provider] = accounts;
+    writeQuotaState(hqRoot, state);
+    return state;
+}
+function resetStillAhead(iso, now) {
+    if (!iso)
+        return false;
+    const ts = Date.parse(iso);
+    return Number.isFinite(ts) && ts > now.getTime();
+}
+/**
+ * Skip an account only for the models it cannot run. An account-wide reset
+ * blocks every model. A needs-credits marker blocks only that model, with
+ * no expiry. A past reset does not block.
+ */
+export function quotaBlockFor(state, provider, accountId, model, now) {
+    const account = state.providers[provider]?.[accountId];
+    if (!account)
+        return { blocked: false };
+    if (resetStillAhead(account.all_models_quota_reset_at, now)) {
+        return {
+            blocked: true,
+            reason: "account_quota_exhausted",
+            quota_reset_at: account.all_models_quota_reset_at,
+            model,
+        };
+    }
+    if (!model)
+        return { blocked: false };
+    const entry = account.models[model];
+    if (!entry)
+        return { blocked: false };
+    if (entry.needs_credits) {
+        return {
+            blocked: true,
+            reason: "account_model_unavailable",
+            marker: entry.marker ?? `needs credits for ${model}`,
+            model,
+        };
+    }
+    if (resetStillAhead(entry.quota_reset_at, now)) {
+        return {
+            blocked: true,
+            reason: "account_quota_exhausted",
+            quota_reset_at: entry.quota_reset_at,
+            model,
+        };
+    }
+    return { blocked: false };
+}
+export function accountQuotaView(state, provider, accountId) {
+    const account = state.providers[provider]?.[accountId];
+    if (!account)
+        return { quota_reset_at: null, model_quota: [] };
+    const model_quota = Object.entries(account.models)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([model, entry]) => {
+        const row = { model };
+        if (entry.quota_reset_at)
+            row.quota_reset_at = entry.quota_reset_at;
+        if (entry.needs_credits)
+            row.needs_credits = true;
+        if (entry.marker)
+            row.marker = entry.marker;
+        return row;
+    });
+    return {
+        quota_reset_at: account.all_models_quota_reset_at ?? null,
+        model_quota,
+    };
+}
+//# sourceMappingURL=quota.js.map

package/dist/lib/lanes/reconcile-install.d.ts

@@ -0,0 +1,69 @@
+/**
+ * systemd user timer install for the lanes reconcile pass.
+ *
+ * Policy: hq-infra-watchdogs-systemd-not-session. The pass is a oneshot
+ * invoked by a timer, never a session-bound background job. Install writes
+ * unit files under a systemd user dir and is idempotent and reversible.
+ * Enabling the timer is optional — the CLI pass works without it.
+ */
+export declare const RECONCILE_TIMER_INTERVAL = "1min";
+export interface ProviderPathEnv {
+    /** PATH for the systemd unit: resolved provider dirs, systemd defaults, then the shell PATH. */
+    path: string;
+    /** Providers whose binary resolved on the installing shell's PATH. */
+    resolved: string[];
+    /** Providers whose binary did not resolve. Reported, never fatal on their own. */
+    unresolved: string[];
+}
+/**
+ * Resolve provider commands with the installing shell's PATH. The resulting
+ * directories are carried into the systemd unit, whose default PATH is too
+ * narrow for per-user provider installations.
+ *
+ * A default config enables one account per provider, so `providers` usually
+ * names every provider even on a box with one installed. A provider that does
+ * not resolve is reported in `unresolved`; the install only refuses when none
+ * of the requested providers resolves, because then the timer has nothing to
+ * run.
+ */
+export declare function providerPathEnv(providers: readonly string[], pathEnv?: string | undefined): ProviderPathEnv;
+export interface RunCommandResult {
+    status: number;
+    stdout?: string;
+    stderr?: string;
+}
+export type RunCommand = (command: string, args: string[]) => RunCommandResult;
+export interface ReconcileInstallOpts {
+    systemdRoot: string;
+    hqRoot: string;
+    nodeBinary?: string;
+    hqBinary?: string;
+    pathEnv?: string;
+    home?: string;
+    enable?: boolean;
+    runCommand?: RunCommand;
+}
+export interface ReconcileInstallResult {
+    ok: true;
+    action: "reconcile.install" | "reconcile.uninstall";
+    systemd_root: string;
+    unit: string;
+    timer: string;
+    written?: boolean;
+    enabled?: boolean;
+    removed?: boolean;
+}
+export declare function renderReconcileService(opts: {
+    nodeBinary: string;
+    hqBinary: string;
+    hqRoot: string;
+    home?: string;
+    pathEnv?: string;
+}): string;
+export declare function renderReconcileTimer(): string;
+export declare function defaultSystemdUserDir(home?: string): string;
+export declare function installReconcileTimer(opts: ReconcileInstallOpts): ReconcileInstallResult;
+export declare function uninstallReconcileTimer(opts: Pick<ReconcileInstallOpts, "systemdRoot" | "runCommand"> & {
+    disable?: boolean;
+}): ReconcileInstallResult;
+//# sourceMappingURL=reconcile-install.d.ts.map

package/dist/lib/lanes/reconcile-install.js

@@ -0,0 +1,221 @@
+/**
+ * systemd user timer install for the lanes reconcile pass.
+ *
+ * Policy: hq-infra-watchdogs-systemd-not-session. The pass is a oneshot
+ * invoked by a timer, never a session-bound background job. Install writes
+ * unit files under a systemd user dir and is idempotent and reversible.
+ * Enabling the timer is optional — the CLI pass works without it.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { LanesError } from "./errors.js";
+import { RECONCILE_TIMER_NAME, RECONCILE_UNIT_NAME } from "./reconcile.js";
+import { resolveHqBinary, resolveNodeBinary, } from "../mesh/live/daemon/install.js";
+import { SYSTEMD_PATH_ENV } from "../service-manager/systemd.js";
+export const RECONCILE_TIMER_INTERVAL = "1min";
+/**
+ * Resolve provider commands with the installing shell's PATH. The resulting
+ * directories are carried into the systemd unit, whose default PATH is too
+ * narrow for per-user provider installations.
+ *
+ * A default config enables one account per provider, so `providers` usually
+ * names every provider even on a box with one installed. A provider that does
+ * not resolve is reported in `unresolved`; the install only refuses when none
+ * of the requested providers resolves, because then the timer has nothing to
+ * run.
+ */
+export function providerPathEnv(providers, pathEnv = process.env.PATH) {
+    const searched = pathEnv ?? "";
+    const directories = searched.split(path.delimiter).filter(Boolean);
+    const resolvedDirs = [];
+    const resolved = [];
+    const unresolved = [];
+    for (const provider of providers) {
+        const found = directories.find((directory) => {
+            try {
+                fs.accessSync(path.join(directory, provider), fs.constants.X_OK);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        if (!found) {
+            unresolved.push(provider);
+            continue;
+        }
+        resolved.push(provider);
+        // Keep the real binary's directory, not only a wrapper directory that
+        // happened to be on the installing shell's PATH. Systemd must be able to
+        // invoke the resolved provider after it starts with its own environment.
+        resolvedDirs.push(path.dirname(fs.realpathSync(path.join(found, provider))));
+    }
+    if (providers.length > 0 && resolved.length === 0) {
+        throw new LanesError("provider_binary_unresolved", `Cannot resolve any provider binary (${providers.join(", ")}) from PATH`, { providers: [...providers], searched_path: searched });
+    }
+    return {
+        path: [...new Set([...resolvedDirs, ...SYSTEMD_PATH_ENV.split(":"), ...directories])]
+            .filter(Boolean)
+            .join(":"),
+        resolved,
+        unresolved,
+    };
+}
+function shellQuote(v) {
+    return /^[A-Za-z0-9_./:-]+$/.test(v) ? v : `'${v.replace(/'/g, `'\\''`)}'`;
+}
+export function renderReconcileService(opts) {
+    const exec = [opts.nodeBinary, opts.hqBinary, "lanes", "reconcile"]
+        .map(shellQuote)
+        .join(" ");
+    const home = opts.home ?? os.homedir();
+    const pathEnv = opts.pathEnv ?? SYSTEMD_PATH_ENV;
+    return `[Unit]
+Description=HQ lanes reconcile pass
+Documentation=file://personal/projects/hq-cli-lanes/SPEC.md
+
+[Service]
+Type=oneshot
+ExecStart=${exec}
+WorkingDirectory=${shellQuote(opts.hqRoot)}
+Nice=10
+Environment=HOME=${shellQuote(home)}
+Environment=PATH=${shellQuote(pathEnv)}
+Environment=HQ_ROOT=${shellQuote(opts.hqRoot)}
+Environment=HQ_NO_UPDATE_CHECK=1
+KillMode=process
+
+[Install]
+WantedBy=default.target
+`;
+}
+export function renderReconcileTimer() {
+    return `[Unit]
+Description=Periodic HQ lanes reconcile pass
+
+[Timer]
+OnBootSec=30s
+OnUnitActiveSec=${RECONCILE_TIMER_INTERVAL}
+AccuracySec=10s
+Persistent=true
+Unit=${RECONCILE_UNIT_NAME}
+
+[Install]
+WantedBy=timers.target
+`;
+}
+export function defaultSystemdUserDir(home = os.homedir()) {
+    return path.join(home, ".config", "systemd", "user");
+}
+function writeIfChanged(filePath, contents) {
+    try {
+        const existing = fs.readFileSync(filePath, "utf8");
+        if (existing === contents)
+            return false;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code !== "ENOENT")
+            throw err;
+    }
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+    try {
+        fs.writeFileSync(tmp, contents, { encoding: "utf8", mode: 0o644 });
+        fs.renameSync(tmp, filePath);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch (unlinkErr) {
+            const unlinkCode = unlinkErr.code;
+            if (unlinkCode !== "ENOENT") {
+                process.stderr.write(`hq lanes reconcile install: unlink tmp failed for ${tmp}: ${unlinkErr instanceof Error ? unlinkErr.message : String(unlinkErr)}\n`);
+            }
+        }
+        throw err;
+    }
+    return true;
+}
+function unlinkIfExists(filePath) {
+    try {
+        fs.unlinkSync(filePath);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === "ENOENT")
+            return false;
+        throw err;
+    }
+}
+function runSystemctl(args, runCommand) {
+    const result = runCommand("systemctl", args);
+    if (result.status !== 0) {
+        throw new LanesError("systemd_failed", `systemctl ${args.join(" ")} failed: ${(result.stderr ?? "").trim() || `exit ${result.status}`}`, { args, status: result.status, stderr: result.stderr });
+    }
+}
+export function installReconcileTimer(opts) {
+    const nodeBinary = opts.nodeBinary ?? resolveNodeBinary();
+    const hqBinary = opts.hqBinary ?? resolveHqBinary();
+    const unitPath = path.join(opts.systemdRoot, RECONCILE_UNIT_NAME);
+    const timerPath = path.join(opts.systemdRoot, RECONCILE_TIMER_NAME);
+    const unitChanged = writeIfChanged(unitPath, renderReconcileService({
+        nodeBinary,
+        hqBinary,
+        hqRoot: opts.hqRoot,
+        home: opts.home,
+        pathEnv: opts.pathEnv,
+    }));
+    const timerChanged = writeIfChanged(timerPath, renderReconcileTimer());
+    let enabled = false;
+    if (opts.enable) {
+        if (!opts.runCommand) {
+            throw new LanesError("systemd_enable_requires_runner", "--enable needs a systemctl runner; pass runCommand or omit --enable to write unit files only", {});
+        }
+        runSystemctl(["--user", "daemon-reload"], opts.runCommand);
+        runSystemctl(["--user", "enable", "--now", RECONCILE_TIMER_NAME], opts.runCommand);
+        enabled = true;
+    }
+    return {
+        ok: true,
+        action: "reconcile.install",
+        systemd_root: opts.systemdRoot,
+        unit: unitPath,
+        timer: timerPath,
+        written: unitChanged || timerChanged,
+        enabled,
+    };
+}
+export function uninstallReconcileTimer(opts) {
+    if (opts.disable) {
+        if (!opts.runCommand) {
+            throw new LanesError("systemd_enable_requires_runner", "--disable needs a systemctl runner", {});
+        }
+        const disable = opts.runCommand("systemctl", [
+            "--user",
+            "disable",
+            "--now",
+            RECONCILE_TIMER_NAME,
+        ]);
+        if (disable.status !== 0) {
+            process.stderr.write(`hq lanes reconcile uninstall: systemctl disable exited ${disable.status}: ${(disable.stderr ?? "").trim()}\n`);
+        }
+        opts.runCommand("systemctl", ["--user", "daemon-reload"]);
+    }
+    const unitPath = path.join(opts.systemdRoot, RECONCILE_UNIT_NAME);
+    const timerPath = path.join(opts.systemdRoot, RECONCILE_TIMER_NAME);
+    const removedUnit = unlinkIfExists(unitPath);
+    const removedTimer = unlinkIfExists(timerPath);
+    return {
+        ok: true,
+        action: "reconcile.uninstall",
+        systemd_root: opts.systemdRoot,
+        unit: unitPath,
+        timer: timerPath,
+        removed: removedUnit || removedTimer,
+    };
+}
+//# sourceMappingURL=reconcile-install.js.map