@cruxy/cli 1.3.0 → 1.5.0

package/dist/config/manager.js

@@ -59,18 +59,35 @@ function rejectProjectScopeHeaders(obj, file) {
         }
     }
 }
+/**
+ * Which environment variable overrides which config path — a TABLE rather than
+ * a run of `if`s, because two surfaces need it read in opposite directions:
+ * this file turns variables into a layer, and the settings view turns a layer
+ * back into "which variable is doing this". A second hand-written copy of the
+ * mapping would drift on the first variable added, and the copy that drifts is
+ * the one telling the user where the value came from.
+ */
+export const ENV_OVERRIDES = [
+    { envVar: "CRUXY_MODEL", path: "model.model" },
+    { envVar: "CRUXY_PROVIDER", path: "model.provider" },
+    { envVar: "CRUXY_LOG_LEVEL", path: "logLevel" },
+];
 /** Overrides sourced from environment variables. */
 function envOverrides() {
     const out = {};
-    const model = {};
-    if (process.env.CRUXY_MODEL)
-        model.model = process.env.CRUXY_MODEL;
-    if (process.env.CRUXY_PROVIDER)
-        model.provider = process.env.CRUXY_PROVIDER;
-    if (Object.keys(model).length)
-        out.model = model;
-    if (process.env.CRUXY_LOG_LEVEL)
-        out.logLevel = process.env.CRUXY_LOG_LEVEL;
+    for (const { envVar, path } of ENV_OVERRIDES) {
+        const value = process.env[envVar];
+        if (!value)
+            continue;
+        const keys = path.split(".");
+        let cursor = out;
+        for (const key of keys.slice(0, -1)) {
+            if (!isPlainObject(cursor[key]))
+                cursor[key] = {};
+            cursor = cursor[key];
+        }
+        cursor[keys[keys.length - 1]] = value;
+    }
     return out;
 }
 /**
@@ -83,15 +100,23 @@ export function loadConfig(opts = {}) {
         project: null,
         explicit: null,
     };
+    const layers = {
+        global: null,
+        project: null,
+        explicit: null,
+        env: {},
+    };
     let merged = {};
     const gPath = globalConfigPath();
     if (existsSync(gPath)) {
-        merged = deepMerge(merged, readJsonFile(gPath));
+        layers.global = readJsonFile(gPath);
+        merged = deepMerge(merged, layers.global);
         sources.global = gPath;
     }
     if (opts.configPath) {
         const obj = readJsonFile(opts.configPath);
         rejectProjectScopeHeaders(obj, opts.configPath);
+        layers.explicit = obj;
         merged = deepMerge(merged, obj);
         sources.explicit = opts.configPath;
     }
@@ -100,11 +125,13 @@ export function loadConfig(opts = {}) {
         if (pPath) {
             const obj = readJsonFile(pPath);
             rejectProjectScopeHeaders(obj, pPath);
+            layers.project = obj;
             merged = deepMerge(merged, obj);
             sources.project = pPath;
         }
     }
-    merged = deepMerge(merged, envOverrides());
+    layers.env = envOverrides();
+    merged = deepMerge(merged, layers.env);
     const result = CruxyConfigSchema.safeParse(merged);
     if (!result.success) {
         const issues = result.error.issues
@@ -112,7 +139,7 @@ export function loadConfig(opts = {}) {
             .join("\n");
         throw configInvalid(issues, sources.project ?? sources.global ?? undefined);
     }
-    return { config: result.data, sources };
+    return { config: result.data, sources, layers };
 }
 /** Resolve a dot-path (e.g. "model.temperature") against a config object. */
 export function getPath(obj, path) {
@@ -176,12 +203,15 @@ export function resolveApiKey(provider) {
 }
 /** The API key from the environment for `provider`, or `undefined`. */
 function envApiKey(provider) {
-    switch (provider) {
-        case "cruxy":
-            return process.env.CRUXY_API_KEY;
-        case "openai":
-            return process.env.OPENAI_API_KEY;
-        default:
-            return process.env.CRUXY_API_KEY;
-    }
+    return process.env[apiKeyEnvVar(provider)];
+}
+/**
+ * The environment variable a provider's API key is read from — the NAME only,
+ * never the value, so a surface can say where a key would come from without
+ * ever holding one. Exported so nothing has to restate this mapping: a second
+ * copy would drift the moment a provider is added, and the copy that drifts is
+ * always the one telling the user where to put their key.
+ */
+export function apiKeyEnvVar(provider) {
+    return provider === "openai" ? "OPENAI_API_KEY" : "CRUXY_API_KEY";
 }

package/dist/errors/constructors.js

@@ -1,4 +1,4 @@
-import { ApiError, AuthError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { ApiError, AuthError, BudgetExhaustedError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
 import { scrubModelNames } from "../brand/index.js";
 import { CruxyError, ErrorCode } from "./types.js";
 /**
@@ -223,14 +223,92 @@ export function apiOverloaded(underlying) {
         underlying,
     });
 }
+/**
+ * A wait, in the largest unit that stays honest: "4h", "12m", "18d".
+ *
+ * `apiRateLimit` renders seconds because a rate-limit wait IS seconds. A budget
+ * window is hours or days, and "~14400s" is a number a human has to do
+ * arithmetic on at the moment they are least inclined to.
+ */
+function humanWait(ms) {
+    const minutes = Math.round(ms / 60_000);
+    if (minutes < 60)
+        return `${Math.max(1, minutes)}m`;
+    const hours = Math.round(minutes / 60);
+    return hours < 48 ? `${hours}h` : `${Math.round(hours / 24)}d`;
+}
+/**
+ * The weighted-pool gate refused the request (429 `budget_exhausted`).
+ *
+ * THIS IS THE POOL, AND ONLY THE POOL. The gateway spends separate codes on the
+ * things a user actually can pay their way out of — `credits_exhausted`,
+ * `key_spend_cap_exceeded`, `workspace_spend_cap_exceeded` — and none of them
+ * arrive here. So the advice this used to give ("top up or raise your budget,
+ * then retry") was wrong in both halves: there is nothing to top up on a
+ * subscription pool, and "retry" against a window that refills on a clock is an
+ * instruction to hammer a gate that will refuse again.
+ *
+ * That wording was harmless while it was unreachable from this CLI. cruxy-ai/api#174
+ * makes a CLI login mint a subscription credential, so it is now the message a
+ * blocked user actually reads — see cruxy-ai/cli#212.
+ *
+ * The error already carries everything needed to say something true, and all of
+ * it used to be discarded:
+ *
+ *  - `miraAvailable` — mira is exempt from the pool kill, so on most denials
+ *    there IS a way to keep working. It goes first: it is the only step that
+ *    unblocks someone now rather than telling them when to come back.
+ *  - `window` — "monthly" and "burst" are different waits (a calendar rollover
+ *    versus a trailing sum sliding back under its cap), so the wait is named.
+ *  - `resetAt` / `retryAfterMs` — WHEN, so the wait is a time rather than a
+ *    vague "later". The window length is deliberately not asserted here; the
+ *    server sends the recovery instant and this reports that.
+ */
 export function budgetExhausted(underlying) {
+    const err = underlying instanceof BudgetExhaustedError ? underlying : undefined;
+    const waitMs = err?.retryAfterMs ??
+        (err?.resetAt !== undefined ? msUntil(err.resetAt) : undefined);
+    const nextSteps = [];
+    // Mira stays available on an exhausted pool (it is the always-available
+    // floor), so when the gateway says so, the first step is the one that gets
+    // the user working again instead of waiting.
+    if (err?.miraAvailable) {
+        nextSteps.push("switch to the mira tier, which stays available: `/model mira`");
+    }
+    const window = err?.window === "burst" ? "burst" : err?.window;
+    const windowPhrase = window ? `your ${window} budget window` : "your budget";
+    nextSteps.push(waitMs !== undefined && waitMs > 0
+        ? `wait ~${humanWait(waitMs)} — ${windowPhrase} recovers then`
+        : `wait for ${windowPhrase} to recover`);
+    // Only where it is true. A subscription pool is not something a user can add
+    // to; a plan change is the only lever, and it is a different action from
+    // "top up" with a different place to do it.
+    nextSteps.push("or move to a higher plan for a larger allowance");
     return new CruxyError({
         code: ErrorCode.BudgetExhausted,
-        title: "your Cruxy budget is exhausted",
+        title: window
+            ? `your ${window} Cruxy budget is exhausted`
+            : "your Cruxy budget is exhausted",
         cause: scrubbedMessageOf(underlying),
-        nextSteps: ["top up or raise your budget, then retry"],
+        nextSteps,
         underlying,
-    });
+        meta: err
+            ? {
+                ...(err.window !== undefined ? { window: err.window } : {}),
+                ...(err.resetAt !== undefined ? { resetAt: err.resetAt } : {}),
+                ...(err.miraAvailable !== undefined
+                    ? { miraAvailable: err.miraAvailable }
+                    : {}),
+            }
+            : undefined,
+    });
+}
+/** Milliseconds until an ISO instant, or `undefined` if it is absent/unparseable. */
+function msUntil(iso) {
+    const at = Date.parse(iso);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, at - Date.now());
 }
 // ── filesystem (exit 7) ───────────────────────────────────────────────────────
 export function fileNotFound(path, underlying) {
@@ -1309,12 +1387,14 @@ export function classifyProviderError(underlying) {
         return apiOverloaded(underlying);
     if (underlying instanceof NetworkError)
         return gatewayUnreachable(underlying);
-    if (underlying instanceof ApiError) {
-        // BudgetExhaustedError isn't exported by the SDK; match by name.
-        if (underlying.name === "BudgetExhaustedError") {
-            return budgetExhausted(underlying);
-        }
-        return apiError(underlying);
+    // Before the `ApiError` base it extends, like every other subclass here. The
+    // name check this replaces was a workaround for an export that exists — the
+    // SDK's barrel has always re-exported the class — and it silently stopped
+    // matching anything the moment a bundler minified the constructor name.
+    if (underlying instanceof BudgetExhaustedError) {
+        return budgetExhausted(underlying);
     }
+    if (underlying instanceof ApiError)
+        return apiError(underlying);
     return null;
 }

package/dist/limits/cache.js

@@ -0,0 +1,100 @@
+import { reduceLimits } from "./reduce.js";
+/**
+ * How long a probe's answer is treated as current. The pool moves when the user
+ * spends, and the surfaces that spend it (this CLI, web chat, desktop) do so in
+ * turns — so a per-turn refresh is the natural cadence and this floor exists
+ * only to coalesce the several triggers a single turn can produce.
+ */
+const MIN_INTERVAL_MS = 15_000;
+export class LimitsCache {
+    probe;
+    now;
+    minIntervalMs;
+    state;
+    /** The refresh in flight, so concurrent triggers share one request. */
+    inFlight = null;
+    lastAttemptAt = 0;
+    constructor(
+    /**
+     * Absent when there is no credential to ask with. That is not a failure to
+     * report later — it is knowable now, costs no request to determine, and the
+     * panel's answer ("sign in") is the same either way.
+     */
+    probe, opts = {}) {
+        this.probe = probe;
+        this.now = opts.now ?? Date.now;
+        this.minIntervalMs = opts.minIntervalMs ?? MIN_INTERVAL_MS;
+        this.state = probe
+            ? { status: "pending" }
+            : { status: "error", reason: "unauthenticated" };
+    }
+    /** The last settled state — a field read, safe from the paint path. */
+    current() {
+        return this.state;
+    }
+    /** True once a reading has been obtained, whatever has happened since. */
+    hasReading() {
+        return this.state.status === "ready";
+    }
+    /**
+     * Re-read the limits, off the paint path. Coalesces concurrent callers onto
+     * one request and declines to re-probe within {@link minIntervalMs} of the
+     * last attempt.
+     *
+     * Never rejects: a refresh is a background probe for a status panel, and a
+     * caller that has to `.catch` a status update will eventually forget to.
+     */
+    async refresh() {
+        if (!this.probe)
+            return;
+        if (this.inFlight)
+            return this.inFlight;
+        const at = this.now();
+        // The floor applies only once something is on screen. Before the first
+        // answer there is nothing to protect, and rate-limiting our way to a blank
+        // panel would be the floor working against its own purpose.
+        if (this.state.status === "ready" &&
+            at - this.lastAttemptAt < this.minIntervalMs) {
+            return;
+        }
+        this.lastAttemptAt = at;
+        this.inFlight = this.run(this.probe);
+        try {
+            await this.inFlight;
+        }
+        finally {
+            this.inFlight = null;
+        }
+    }
+    async run(probe) {
+        try {
+            const res = await probe();
+            this.state = { status: "ready", reading: reduceLimits(res, this.now()) };
+        }
+        catch (err) {
+            // Keep a good reading rather than blanking a panel that was correct a
+            // moment ago; only report an error when there is nothing else to say.
+            if (this.state.status === "ready")
+                return;
+            this.state = { status: "error", reason: classify(err) };
+        }
+    }
+}
+/**
+ * Why the probe failed, in the three distinctions a user can act on.
+ *
+ * Matched on the SDK's error class names rather than `instanceof`, so this stays
+ * a pure classification with no import of the transport into a module the TUI
+ * loads. A 404/501 is the interesting case: it means a gateway that does not
+ * serve `/limits` at all — an older deployment, or a base URL pointed somewhere
+ * else entirely — and telling that user "you are offline" would send them
+ * debugging a network that is working fine.
+ */
+function classify(err) {
+    const e = err;
+    if (e?.name === "AuthError")
+        return "unauthenticated";
+    if (e?.status === 404 || e?.status === 501)
+        return "unsupported";
+    return "unreachable";
+}

package/dist/limits/index.js

@@ -0,0 +1,11 @@
+/**
+ * Limits (P9): the gateway's own account of what this credential may spend, and
+ * how much of it is left.
+ *
+ * Three files, one direction: `reduce.ts` turns the wire response into the
+ * closed {@link LimitsReading} union, `cache.ts` owns the network read and the
+ * staleness rules, and `types.ts` holds the union both sides agree on. The
+ * rendering lives in `tui/limits-panel.ts` — nothing here formats anything.
+ */
+export { LimitsCache } from "./cache.js";
+export { reduceLimits, bindingWindow, usedFraction } from "./reduce.js";

package/dist/limits/reduce.js

@@ -0,0 +1,172 @@
+/**
+ * Wire response → {@link LimitsReading}: one place where "which absence means
+ * what" is decided (P9).
+ *
+ * The reduction is driven by `bucket` and NOTHING else. Not by how the user
+ * logged in, not by whether a key looks like `cxy_live_`, not by which config
+ * fields are set — every one of those was a plausible inference and every one of
+ * them is now wrong, because the gateway changed which bucket a CLI login mints
+ * into (cruxy-ai/api#174) without changing anything a client could see locally.
+ * The endpoint is the answer to that question; asking anything else is guessing.
+ */
+/** A cap is only a denominator when it is a positive, finite number. */
+function usableCap(cap) {
+    return Number.isFinite(cap) && cap > 0;
+}
+/**
+ * A weighted-token window, or `undefined` when it cannot serve as a fraction.
+ *
+ * A cap of 0 is dropped rather than rendered as "100% used": zero is what an
+ * unprovisioned or misconfigured plan reports, and dividing by it produces
+ * either a crash or a full red bar, neither of which is a true statement about
+ * what the user may spend.
+ */
+function toWindow(w) {
+    if (!w || !usableCap(w.cap))
+        return undefined;
+    return {
+        cap: w.cap,
+        used: w.used,
+        remaining: w.remaining,
+        ...(w.state !== undefined ? { state: w.state } : {}),
+        ...(w.resets_at !== undefined ? { resetsAt: w.resets_at } : {}),
+    };
+}
+function toSpendCap(c) {
+    if (!c || !usableCap(c.cap))
+        return undefined;
+    return {
+        cap: c.cap,
+        spent: c.spent,
+        remaining: c.remaining,
+        ...(c.resets_at !== undefined ? { resetsAt: c.resets_at } : {}),
+    };
+}
+function toRateWindow(w) {
+    return {
+        limit: w.limit,
+        remaining: w.remaining,
+        windowSeconds: w.window_seconds,
+        ...(w.resets_at !== undefined ? { resetsAt: w.resets_at } : {}),
+    };
+}
+/**
+ * The budget shape for this credential.
+ *
+ * Ordered by bucket, and each branch answers only for its own bucket — a
+ * `subscription` response that somehow also carried `credits` does not get to
+ * fall through into the headless branch. The server decides which section is
+ * authoritative by telling us the bucket; honouring that literally is what keeps
+ * this reduction and the gate in agreement.
+ */
+function reduceBudget(res) {
+    switch (res.bucket) {
+        case "subscription": {
+            const pool = res.token_pool;
+            // No section at all: gated by something we were not told about.
+            if (!pool)
+                return { kind: "unknown" };
+            // Enterprise. The one place "no numbers" is a complete answer.
+            if (!pool.enforced)
+                return { kind: "unenforced" };
+            const monthly = toWindow(pool.monthly);
+            const burst = toWindow(pool.burst);
+            // Enforced, but nothing readable to enforce against. NOT "unenforced":
+            // the pool exists and will stop this user, we just cannot say when.
+            if (!monthly && !burst)
+                return { kind: "unknown" };
+            return {
+                kind: "pool",
+                unit: pool.unit ?? "weighted_tokens",
+                ...(pool.state !== undefined ? { state: pool.state } : {}),
+                ...(monthly ? { monthly } : {}),
+                ...(burst ? { burst } : {}),
+                ...(pool.mira && usableCap(pool.mira.cap)
+                    ? {
+                        mira: {
+                            cap: pool.mira.cap,
+                            used: pool.mira.used,
+                            remaining: pool.mira.remaining,
+                            state: pool.mira.state,
+                            window: pool.mira.window,
+                            ...(pool.mira.resets_at !== undefined
+                                ? { resetsAt: pool.mira.resets_at }
+                                : {}),
+                        },
+                    }
+                    : {}),
+                blockedModels: pool.blocked_models ?? [],
+            };
+        }
+        case "apikey":
+            // `metered: true` is the server's positive statement that there is no pool
+            // to report. Its absence on an apikey bucket means this build is reading a
+            // response it does not fully understand, so it says so.
+            return res.metered === true ? { kind: "metered" } : { kind: "unknown" };
+        case "headless": {
+            const c = res.credits;
+            if (!c)
+                return { kind: "unknown" };
+            return {
+                kind: "credits",
+                plan: c.plan,
+                granted: c.granted,
+                used: c.used,
+                remaining: c.remaining,
+                ...(c.resets_at !== undefined ? { resetsAt: c.resets_at } : {}),
+            };
+        }
+        default:
+            // A bucket added after this build. The tier and the rate limits below are
+            // still real and still reported; only the budget shape is unreadable.
+            return { kind: "unknown" };
+    }
+}
+/** Reduce a wire response to the reading the panel consumes. */
+export function reduceLimits(res, readAt = Date.now()) {
+    const chat = res.rate_limits?.chat;
+    const keySpendCap = toSpendCap(res.key_spend_cap);
+    const workspaceSpendCap = toSpendCap(res.workspace_spend_cap);
+    const rate = chat
+        ? {
+            perKey: toRateWindow(chat.per_key),
+            perOrg: toRateWindow(chat.per_org),
+            maxConcurrentRequests: chat.max_concurrent_requests,
+        }
+        : undefined;
+    return {
+        tier: res.tier,
+        bucket: res.bucket,
+        budget: reduceBudget(res),
+        ...(rate ? { chat: rate } : {}),
+        ...(keySpendCap ? { keySpendCap } : {}),
+        ...(workspaceSpendCap ? { workspaceSpendCap } : {}),
+        readAt,
+    };
+}
+/**
+ * The window that will stop this user FIRST — the one the gate itself calls
+ * binding: whichever of monthly/burst has the smaller REMAINING fraction
+ * (`internal/budget/decide.go`).
+ *
+ * This is what earns the single bar the rail has room for. Drawing the month
+ * because it is the bigger number would routinely show a comfortable 6% while
+ * the trailing-12h window — a quarter of the month's cap on every self-serve
+ * tier — is the one about to refuse the next request.
+ */
+export function bindingWindow(monthly, burst) {
+    if (!monthly)
+        return burst ? { window: burst, name: "burst" } : undefined;
+    if (!burst)
+        return { window: monthly, name: "month" };
+    const frac = (w) => w.remaining / w.cap;
+    return frac(burst) < frac(monthly)
+        ? { window: burst, name: "burst" }
+        : { window: monthly, name: "month" };
+}
+/** The fraction of a cap consumed, clamped to [0,1] for display. */
+export function usedFraction(w) {
+    if (!usableCap(w.cap))
+        return undefined;
+    return Math.min(1, Math.max(0, w.used / w.cap));
+}

package/dist/limits/types.js

@@ -0,0 +1,25 @@
+/**
+ * The CLI's reading of `GET /api/v1/limits` (P9).
+ *
+ * THE WIRE SHAPE IS NOT THE RENDER SHAPE, and the gap between them is the whole
+ * reason this module exists. On the wire a section is present or absent and a
+ * reader must know which absence means what: no `token_pool` on an `apikey` is
+ * normal, no `monthly` inside an enforced pool is a gateway this build cannot
+ * read, and `{enforced: false}` is a definite statement that there is no cap —
+ * three absences with three different meanings, one of which must never be shown
+ * as another.
+ *
+ * So the reduction resolves them ONCE, into a closed union where each variant
+ * carries exactly the numbers that variant may legitimately state. A renderer
+ * handed a {@link Unenforced} has no cap to divide by because the type has no
+ * cap in it — the honesty is structural, not a rule someone has to remember at
+ * the call site.
+ *
+ * WHAT THIS ADDS TO `usage/weighted.ts`, which computes the same unit locally:
+ * that module is explicit that it can state consumption and never headroom,
+ * because a cap needs the user's plan and what every OTHER surface (web chat,
+ * desktop, phone) has already spent — "neither of which is on this machine".
+ * This is the other half arriving over the wire: the denominator, already
+ * inclusive of every surface, from the meter itself.
+ */
+export {};