@indigoai-us/hq-cli 5.345.107 → 5.345.109

package/dist/lib/capacity/route.js

@@ -0,0 +1,452 @@
+/**
+ * Pure router for `hq capacity route` and `hq lanes create --account auto`.
+ *
+ * Port of personal/skills/boss-mode/boss-route.mjs into hq-cli. Owner decision
+ * 2026-10-11: all accounts are one pool across companies; the pick names the
+ * account so the board shows which account a lane ran on.
+ *
+ * Reads the ledger via src/lib/capacity/read.ts (NowView), the lane account
+ * registry via src/lib/lanes/config.ts (LanesConfig), and the live lanes list
+ * via src/lib/lanes/store.ts (readAllLanes). No shell to `hq`, no network.
+ *
+ * Returns the same shape as boss-route.mjs:
+ *   { ok, at, request, pick, ranked, skipped, moves, next_reset, capacity,
+ *     lanes_error }
+ */
+import { canonicalizeHome } from "../lanes/config.js";
+import { LANE_PROVIDERS } from "../lanes/types.js";
+/** All lane providers, in the stable order boss-route uses for ranking ties. */
+export const ROUTE_PROVIDERS = LANE_PROVIDERS;
+/** Lane states that count against an account's live load. */
+export const LIVE_STATES = new Set([
+    "running",
+    "queued",
+    "awaiting_input",
+]);
+/** Limit kinds the router scores against. */
+export const LIMIT_KINDS = new Set(["session", "weekly_all", "weekly_scoped"]);
+/** A reading older than this is treated as no reading at all. */
+export const STALE_SKIP_MS = 24 * 36e5;
+/** Headroom below this percent is "nearly used up"; the account is skipped. */
+export const NEARLY_OUT = 5;
+/** Score penalty per live lane already on the account. */
+export const LANE_PENALTY = 3;
+/** Weekly reset within this window boosts an otherwise idle account. */
+export const RESET_SOON_MS = 24 * 36e5;
+/** Score bonus for a weekly that resets within RESET_SOON_MS. */
+export const RESET_SOON_BONUS = 10;
+/** A limit reading older than this is dropped as unknown until its window resets. */
+export const LIMIT_STALE_MS = 24 * 36e5;
+/** Readings older than this rank below fresh ones by OLD_READING_PENALTY. */
+export const FRESH_MS = 60 * 6e4;
+/** Score penalty for an account whose binding limit reading is not fresh. */
+export const OLD_READING_PENALTY = 10;
+/** Default --floor applied by the CLI (percent headroom to clear). */
+export const DEFAULT_FLOOR = 15;
+/** Default --prefer order applied by the CLI. */
+export const DEFAULT_PREFER = LANE_PROVIDERS;
+/** Sign-in states a lane can still run on. */
+export const RUNNABLE_AUTH = new Set(["ok", "expired"]);
+/** Map a model id to its lane provider, or null when the model is unmapped. */
+export function providerForModel(model) {
+    const s = model.toLowerCase();
+    if (/claude|fable|opus|sonnet|haiku/.test(s))
+        return "claude";
+    if (/gpt|codex|^o\d/.test(s))
+        return "codex";
+    if (/grok/.test(s))
+        return "grok";
+    return null;
+}
+/** True when the limit should factor into the pick for this request. */
+export function limitApplies(provider, limit, model) {
+    if (!LIMIT_KINDS.has(limit.kind))
+        return false;
+    if (limit.kind !== "weekly_scoped")
+        return true;
+    if (provider === "grok")
+        return true;
+    if (!model || !limit.scope)
+        return false;
+    return model.toLowerCase().includes(String(limit.scope).toLowerCase());
+}
+/** Human label for the limit a reason or binding row quotes. */
+export function labelLimit(limit) {
+    if (limit.kind === "session")
+        return "session (5h)";
+    if (limit.kind === "weekly_all")
+        return "weekly";
+    return `${limit.scope ?? "scoped"} weekly`;
+}
+/** Lane account whose canonical home matches one of the ledger account's homes. */
+export function laneAccountFor(provider, homes, lanesConfig) {
+    const accounts = lanesConfig.providers?.[provider]?.accounts ?? {};
+    if (!homes || homes.length === 0)
+        return null;
+    const wanted = new Set(homes.map((h) => safeCanonical(h)));
+    for (const [id, cfg] of Object.entries(accounts)) {
+        if (!cfg?.home)
+            continue;
+        if (wanted.has(safeCanonical(cfg.home))) {
+            return { id, enabled: cfg.enabled !== false };
+        }
+    }
+    return null;
+}
+function safeCanonical(home) {
+    try {
+        return canonicalizeHome(home);
+    }
+    catch {
+        return home;
+    }
+}
+export class RouteUsageError extends Error {
+    code = "route_usage";
+    constructor(message) {
+        super(message);
+        this.name = "RouteUsageError";
+    }
+}
+/** Parse `--provider any|claude|codex|grok[,..]` honouring the model expansion rule. */
+export function resolveRequestedProviders(raw, model) {
+    const values = (raw ?? ["any"]).map((p) => p.trim()).filter(Boolean);
+    if (values.length === 0)
+        return [...ROUTE_PROVIDERS];
+    if (values.includes("any")) {
+        if (model) {
+            const mapped = providerForModel(model);
+            if (mapped)
+                return [mapped];
+        }
+        return [...ROUTE_PROVIDERS];
+    }
+    const out = [];
+    for (const value of values) {
+        if (!isLaneProvider(value)) {
+            throw new RouteUsageError(`unknown provider: ${value}`);
+        }
+        if (!out.includes(value))
+            out.push(value);
+    }
+    return out;
+}
+/** Parse `--prefer claude,codex,grok`. */
+export function resolvePreferOrder(raw) {
+    const values = (raw ?? [...ROUTE_PROVIDERS]).map((p) => p.trim()).filter(Boolean);
+    const out = [];
+    for (const value of values) {
+        if (!isLaneProvider(value)) {
+            throw new RouteUsageError(`unknown provider in --prefer: ${value}`);
+        }
+        if (!out.includes(value))
+            out.push(value);
+    }
+    if (out.length === 0)
+        return [...ROUTE_PROVIDERS];
+    return out;
+}
+/** Parse `--floor <n>`; 0..100 inclusive, default DEFAULT_FLOOR when missing. */
+export function resolveFloor(raw) {
+    if (raw === undefined || raw === "")
+        return DEFAULT_FLOOR;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < 0 || value > 100) {
+        throw new RouteUsageError("--floor must be 0 to 100");
+    }
+    return value;
+}
+function isLaneProvider(value) {
+    return ROUTE_PROVIDERS.includes(value);
+}
+function liveLaneCount(lanes, provider, account) {
+    let count = 0;
+    for (const lane of lanes) {
+        if (lane.provider !== provider)
+            continue;
+        if (lane.account !== account)
+            continue;
+        if (!LIVE_STATES.has(lane.state))
+            continue;
+        count += 1;
+    }
+    return count;
+}
+function limitAgeMs(view, nowMs) {
+    if (!view.resetPassed || !view.limit.resetsAt)
+        return view.readAge;
+    const resetMs = Date.parse(view.limit.resetsAt);
+    if (!Number.isFinite(resetMs))
+        return view.readAge;
+    return Math.min(view.readAge, Math.max(0, nowMs - resetMs));
+}
+/**
+ * Pure routing decision over a snapshot: scores every signed-in lane account,
+ * applies the --prefer order under the --floor headroom, returns the pick (or
+ * null when nothing has room), and the lane-move suggestions for live lanes
+ * sitting on bad accounts.
+ */
+export function pickAccount(input) {
+    const nowDate = input.now;
+    const nowMs = nowDate.getTime();
+    const model = (input.model ?? "").trim();
+    const requested = resolveRequestedProviders(input.providers, model);
+    const prefer = resolvePreferOrder(input.prefer);
+    const floor = resolveFloor(input.floor ?? DEFAULT_FLOOR);
+    const lanes = input.lanes ?? [];
+    const ranked = [];
+    const skipped = [];
+    for (const provider of input.view.providers) {
+        const providerId = provider.provider;
+        if (!isLaneProvider(providerId))
+            continue;
+        const accounts = provider.accounts ?? [];
+        for (const account of accounts) {
+            if (!requested.includes(providerId))
+                continue;
+            const laneMatch = laneAccountFor(providerId, account.homes, input.lanesConfig);
+            const label = account.labels?.[0] ?? account.accountId;
+            const base = {
+                provider: providerId,
+                account: laneMatch?.id ?? null,
+                label,
+                organization: account.organization ?? null,
+            };
+            if (!laneMatch) {
+                skipped.push({
+                    ...base,
+                    reason: "no lane account uses this sign-in",
+                    fix: `hq capacity login ${providerId}`,
+                });
+                continue;
+            }
+            const authState = account.authState ?? "unknown";
+            if (account.signedOut || !RUNNABLE_AUTH.has(authState)) {
+                skipped.push({
+                    ...base,
+                    reason: account.reason ?? `sign-in ${authState}`,
+                    fix: account.fixCommand ?? null,
+                });
+                continue;
+            }
+            const tokenExpired = authState === "expired";
+            if (!laneMatch.enabled) {
+                skipped.push({
+                    ...base,
+                    reason: "usage-only, lanes cannot run on it",
+                    fix: `hq lanes accounts enable ${providerId} ${laneMatch.id}`,
+                });
+                continue;
+            }
+            const observedMs = account.observedAt ? Date.parse(account.observedAt) : NaN;
+            const accountAge = Number.isFinite(observedMs)
+                ? Math.max(0, nowMs - observedMs)
+                : Infinity;
+            if (accountAge > STALE_SKIP_MS) {
+                skipped.push({
+                    ...base,
+                    reason: "no reading in the last 24 hours",
+                    fix: "hq capacity doctor",
+                });
+                continue;
+            }
+            const applicable = (account.limits ?? []).filter((l) => limitApplies(providerId, l, model));
+            const viewRows = applicable.map((limit) => {
+                const resetMs = limit.resetsAt ? Date.parse(limit.resetsAt) : NaN;
+                const resetPassed = limit.state === "reset-pending"
+                    || (Number.isFinite(resetMs) && resetMs <= nowMs);
+                const observedLimit = Date.parse(limit.observedAt || account.observedAt || "");
+                const readAge = Number.isFinite(observedLimit)
+                    ? Math.max(0, nowMs - observedLimit)
+                    : Infinity;
+                if (resetPassed) {
+                    return { limit, used: 0, readAge, resetPassed: true };
+                }
+                if (readAge > LIMIT_STALE_MS) {
+                    return { limit, used: null, readAge, resetPassed: false };
+                }
+                const used = typeof limit.usedPercent === "number" ? limit.usedPercent : null;
+                return { limit, used, readAge, resetPassed: false };
+            });
+            if (tokenExpired) {
+                const readingTimes = applicable
+                    .map((limit) => Date.parse(limit.observedAt || ""))
+                    .filter((ms) => Number.isFinite(ms));
+                const newestReadingMs = readingTimes.length > 0 ? Math.max(...readingTimes) : -Infinity;
+                const accountObservedMs = account.observedAt ? Date.parse(account.observedAt) : NaN;
+                const noFreshReading = !Number.isFinite(newestReadingMs)
+                    || (Number.isFinite(accountObservedMs) && newestReadingMs < accountObservedMs);
+                if (noFreshReading) {
+                    skipped.push({
+                        ...base,
+                        reason: "no fresh reading (sign-in expired)",
+                        fix: account.fixCommand ?? null,
+                    });
+                    continue;
+                }
+            }
+            const exhausted = viewRows.find((row) => !row.resetPassed
+                && row.readAge <= LIMIT_STALE_MS
+                && (row.limit.state === "exhausted" || (typeof row.used === "number" && row.used >= 100)));
+            if (exhausted) {
+                skipped.push({
+                    ...base,
+                    reason: `${labelLimit(exhausted.limit)} used up`,
+                    resets_at: exhausted.limit.resetsAt ?? null,
+                });
+                continue;
+            }
+            const known = viewRows.filter((row) => typeof row.used === "number");
+            if (known.length === 0) {
+                skipped.push({
+                    ...base,
+                    reason: "no usage numbers for this account in the last day",
+                    fix: tokenExpired ? (account.fixCommand ?? null) : "hq capacity doctor",
+                });
+                continue;
+            }
+            const oldest = Math.max(0, ...known.map((row) => limitAgeMs(row, nowMs)));
+            const oldReading = oldest > FRESH_MS;
+            let binding = known[0];
+            for (const row of known)
+                if (row.used > binding.used)
+                    binding = row;
+            const headroom = Math.max(0, 100 - binding.used);
+            if (headroom < NEARLY_OUT) {
+                skipped.push({
+                    ...base,
+                    reason: `${labelLimit(binding.limit)} nearly used up`,
+                    resets_at: binding.limit.resetsAt ?? null,
+                });
+                continue;
+            }
+            const live = liveLaneCount(lanes, providerId, laneMatch.id);
+            const weekly = applicable.find((l) => l.kind === "weekly_all" || (providerId === "grok" && l.kind === "weekly_scoped"));
+            const weeklyResetMs = weekly?.resetsAt ? Date.parse(weekly.resetsAt) : NaN;
+            const resetMs = Number.isFinite(weeklyResetMs) ? weeklyResetMs - nowMs : Infinity;
+            const resetSoon = resetMs > 0 && resetMs <= RESET_SOON_MS && headroom >= 30;
+            const score = headroom
+                - live * LANE_PENALTY
+                + (resetSoon ? RESET_SOON_BONUS : 0)
+                - (oldReading ? OLD_READING_PENALTY : 0);
+            const whyParts = [
+                binding.used === 0
+                    ? "nothing used yet on any limit"
+                    : `${headroom}% left on ${labelLimit(binding.limit)}`,
+            ];
+            if (live)
+                whyParts.push(`${live} live lane${live === 1 ? "" : "s"} already on it`);
+            if (resetSoon)
+                whyParts.push("weekly resets within a day, so unused room is lost");
+            if (oldReading)
+                whyParts.push(`last reading ${Math.round(oldest / 36e5)}h old`);
+            if (tokenExpired)
+                whyParts.push("sign-in renews when the lane starts");
+            ranked.push({
+                provider: providerId,
+                account: laneMatch.id,
+                label,
+                organization: account.organization ?? null,
+                headroom,
+                score,
+                live_lanes: live,
+                reset_soon: resetSoon,
+                token_expired: tokenExpired,
+                reading_age_h: Math.round(oldest / 36e5),
+                binding: {
+                    limit: labelLimit(binding.limit),
+                    used_percent: binding.used,
+                    resets_at: binding.limit.resetsAt ?? null,
+                },
+                weekly_resets_at: weekly?.resetsAt ?? null,
+                why: whyParts.join("; "),
+                lane_flags: `--provider ${providerId} --account ${laneMatch.id}`,
+            });
+        }
+    }
+    ranked.sort((a, b) => b.score - a.score
+        || b.headroom - a.headroom
+        || a.reading_age_h - b.reading_age_h
+        || a.provider.localeCompare(b.provider));
+    let pick = null;
+    for (const p of prefer) {
+        if (!requested.includes(p))
+            continue;
+        const best = ranked.find((r) => r.provider === p);
+        if (best && best.headroom >= floor) {
+            pick = best;
+            break;
+        }
+    }
+    if (!pick && ranked.length > 0)
+        pick = ranked[0];
+    const bad = new Map();
+    for (const row of skipped) {
+        if (row.account)
+            bad.set(`${row.provider}:${row.account}`, row.reason);
+    }
+    for (const row of ranked) {
+        if (row.headroom < floor) {
+            bad.set(`${row.provider}:${row.account}`, `${row.binding.limit} has ${row.headroom}% left`);
+        }
+    }
+    const moves = [];
+    for (const lane of lanes) {
+        if (!LIVE_STATES.has(lane.state))
+            continue;
+        const providerId = lane.provider;
+        if (!isLaneProvider(providerId))
+            continue;
+        if (!lane.account)
+            continue;
+        const key = `${providerId}:${lane.account}`;
+        if (!bad.has(key))
+            continue;
+        const to = ranked.find((r) => r.provider === providerId && r.account !== lane.account && r.headroom >= floor);
+        moves.push({
+            lane_id: lane.lane_id,
+            provider: providerId,
+            from: lane.account,
+            reason: bad.get(key),
+            to: to?.account ?? null,
+            command: to
+                ? `hq lanes message ${lane.lane_id} --account ${to.account} --text "Continue on account ${to.account}; ${lane.account} is out of room."`
+                : null,
+        });
+    }
+    const soonest = skipped
+        .map((row) => row.resets_at ?? null)
+        .filter((v) => !!v)
+        .sort()[0] ?? null;
+    return {
+        ok: !!pick,
+        at: nowDate.toISOString(),
+        request: {
+            providers: requested,
+            model: model || null,
+            prefer,
+            floor,
+        },
+        pick,
+        ranked,
+        skipped,
+        moves,
+        next_reset: pick ? null : soonest,
+        capacity: {
+            generated_at: input.view.generatedAt ?? null,
+            stale: !!input.capacityStale,
+            collector_enabled: input.collectorEnabled ?? null,
+        },
+        lanes_error: input.lanesError ?? null,
+    };
+}
+/** One-line text output used by `--text` and by `--account auto` admission messages. */
+export function formatRouteText(result) {
+    if (result.pick) {
+        const org = result.pick.organization || result.pick.label;
+        return `${result.pick.provider} ${result.pick.account} (${org}): ${result.pick.why}. Use ${result.pick.lane_flags}`;
+    }
+    const soonest = result.next_reset;
+    return `No account has room${soonest ? `; next reset ${soonest}` : ""}.`;
+}
+//# sourceMappingURL=route.js.map