@cruxy/cli 1.8.1 → 1.10.0

package/dist/errors/constructors.js

@@ -1,5 +1,9 @@
-import { ApiError, AuthError, BudgetExhaustedError, InvalidRequestError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { ApiError, AuthError, BudgetExhaustedError, InvalidRequestError, NetworkError, OverloadedError, RateLimitError, ToolSchemaRejectedError, } from "@cruxy/sdk";
 import { scrubModelNames } from "../brand/index.js";
+// Imported from the leaf module DIRECTLY, not via `config/index.js`:
+// `config/credentials.ts` imports this file, so going through the barrel would
+// close an import cycle. `credential-lifetime.ts` imports nothing.
+import { classifyCredentialLifetime } from "../config/credential-lifetime.js";
 import { CruxyError, ErrorCode } from "./types.js";
 /**
  * Helper constructors for {@link CruxyError}. Each encodes the title, the human
@@ -137,11 +141,36 @@ export function authInvalid(underlying) {
         cause: scrubbedMessageOf(underlying),
         nextSteps: [
             "verify your API key is correct and active",
+            "run `cruxy login` to sign in again and replace it",
             "re-export the key and try again",
         ],
         underlying,
     });
 }
+/**
+ * The credential expired. The 401 that surfaced it is byte-identical to the one
+ * a wrong key produces (see {@link ErrorCode.AuthExpired}); what separates them
+ * is the expiry this CLI stored when the key was minted, so this constructor is
+ * only ever reached by a caller that checked it.
+ *
+ * `expiresAt` is echoed because "it expired" invites "when?", and a user who
+ * sees a date three weeks past recognises immediately that this is not a key
+ * they typed wrong today.
+ */
+export function authExpired(expiresAt, underlying) {
+    const when = expiresAt ? ` on ${expiresAt}` : "";
+    return new CruxyError({
+        code: ErrorCode.AuthExpired,
+        title: "your cruxy login has expired",
+        cause: `the stored credential reached the end of its lifetime${when}, and the gateway now refuses it`,
+        nextSteps: [
+            "run `cruxy login` to sign in again — it mints a fresh credential",
+            "or export a long-lived key as CRUXY_API_KEY (the environment always wins over the store)",
+        ],
+        underlying,
+        meta: expiresAt !== undefined ? { expiresAt } : undefined,
+    });
+}
 /**
  * A credential could not be persisted with owner-only permissions, so it was
  * NOT written (C.27c). Chiefly a Windows case: the store's ACL could not be
@@ -216,16 +245,32 @@ export function apiError(underlying) {
  * moment", and they point at the issue tracker with a code to quote, because a
  * report is the one action that actually moves this forward.
  *
- * The gateway's message names the offending tool when a tool is at fault (its
- * validator emits `tool "<name>": ...`), and that name is the single most useful
- * token in the whole error — it turns "cruxy is broken" into a filed issue
- * someone can act on. It is lifted out of the SCRUBBED message, never the raw
- * one, so the U.8 gag can never be undone by this path.
+ * WHEN A TOOL IS AT FAULT the gateway now says so in fields rather than in
+ * prose. A schema over one of its caps answers `invalid_tool_schema` carrying
+ * `tool`, `bound` and `limit`, which the SDK reads onto
+ * {@link ToolSchemaRejectedError} — so the tool name, the cap that was hit and
+ * the number to fit under are all read off the structured half of a contract
+ * whose `code` MAY NOT change, rather than parsed back out of English that MAY.
+ *
+ * That name is the single most useful token in the whole error: it turns "cruxy
+ * is broken" into a filed issue someone can act on, and `bound`/`limit` turn the
+ * report into one a fix can start from. All three ride in `meta` for exactly
+ * that reason, and all three are optional — the gateway omits them when no cap
+ * was reached, and an older one omits them entirely.
+ *
+ * The name is still passed through the model-name scrub before it is shown. It
+ * is our own harness's function name and cannot plausibly be an upstream model
+ * id, but the U.8 gag holding BY CONSTRUCTION on every path out of here is worth
+ * more than the one call it costs — this used to be true only because the name
+ * was cut out of an already-scrubbed string.
  */
 export function apiRequestRejected(underlying) {
     const status = underlying instanceof ApiError ? underlying.status : undefined;
     const cause = scrubbedMessageOf(underlying);
-    const tool = toolNamedIn(cause);
+    const rejected = underlying instanceof ToolSchemaRejectedError ? underlying : undefined;
+    const tool = rejected?.tool === undefined ? undefined : scrubModelNames(rejected.tool);
+    const bound = rejected?.bound;
+    const limit = rejected?.limit;
     return new CruxyError({
         code: ErrorCode.ApiRequestRejected,
         title: tool
@@ -244,46 +289,11 @@ export function apiRequestRejected(underlying) {
         meta: {
             ...(status !== undefined ? { status } : {}),
             ...(tool !== undefined ? { tool } : {}),
+            ...(bound !== undefined ? { bound } : {}),
+            ...(limit !== undefined ? { limit } : {}),
         },
     });
 }
-/**
- * The tool name in a gateway rejection, if it named one.
- *
- * The gateway's tool-schema validator prefixes its complaint with the offending
- * function — `tool "apply_patch": parameters nests deeper than 8 levels` — so
- * one quoted token after the word `tool` is the whole pattern. Anything else
- * yields `undefined` and the caller falls back to generic wording: a WRONG tool
- * name in a bug report is worse than none, so this never guesses.
- *
- * ── TEMPORARY COUPLING, AND IT IS THE WRONG KIND ────────────────────────────
- *
- * This reads the gateway's `error` MESSAGE, and the gateway's own contract
- * (cruxy-ai/api, `internal/httpx/errcode.go`) says the message MAY change while
- * the `code` MAY NOT. So this parses the half that is explicitly allowed to move
- * under us — the exact coupling the code/message split exists to prevent.
- *
- * It is deliberate and bounded: today the code is the generic `invalid_request`,
- * shared with bad JSON, a missing field and an unknown model, so the message is
- * the ONLY thing distinguishing "this build's tool harness is permanently
- * unusable" from "this one request was malformed". The tool name is the single
- * most actionable token in the error and it is worth having; a regex that fails
- * closed is the cheapest way to have it.
- *
- * Failing closed is what makes the risk acceptable. If the gateway rewords, this
- * returns `undefined`, the caller drops to generic wording, and the error is
- * still correct — less specific, never wrong. Nothing downstream branches on it.
- *
- * The real fix is server-side and filed as cruxy-ai/api#183: a distinct 400 code
- * for harness-bound rejections (the `invalid_schema` precedent already exists
- * for `response_format`), with the tool name as a STRUCTURED FIELD rather than a
- * message prefix. When that lands, match on the code, read the field, and delete
- * this function — do not "improve" the regex.
- */
-function toolNamedIn(message) {
-    const match = /\btool "([^"]+)"/.exec(message ?? "");
-    return match?.[1];
-}
 export function apiRateLimit(underlying) {
     const retryAfterMs = underlying instanceof RateLimitError ? underlying.retryAfterMs : undefined;
     return new CruxyError({
@@ -360,25 +370,61 @@ export function budgetExhausted(underlying) {
     if (err?.miraAvailable) {
         nextSteps.push("switch to the mira tier, which stays available: `/model mira`");
     }
+    // WHICH CEILING BOUND. The gateway renders three of them through one body,
+    // separated only by `code`, so this is the one place that can tell them apart —
+    // and they take genuinely different advice. "Move to a higher plan" is right
+    // for the subscription pool and WRONG for a per-key cap: a device-login
+    // credential carries its own monthly ceiling stamped on it at mint, and no
+    // plan a user buys will raise it. Saying so anyway sends someone to spend
+    // money on something that cannot fix their problem.
+    const ceiling = err?.apiType;
+    const isKeyCap = ceiling === "key_spend_cap_exceeded";
+    const isWorkspaceCap = ceiling === "workspace_spend_cap_exceeded";
     const window = err?.window === "burst" ? "burst" : err?.window;
-    const windowPhrase = window ? `your ${window} budget window` : "your budget";
+    const windowPhrase = isKeyCap
+        ? "this key's monthly spend cap"
+        : isWorkspaceCap
+            ? "the workspace's monthly spend cap"
+            : window
+                ? `your ${window} budget window`
+                : "your budget";
+    // "resets" for a cap (a calendar ceiling that refills on the 1st) and
+    // "recovers" for the pool (a window that trickles back) — each the verb that
+    // is actually true of the ceiling being described.
+    const verb = isKeyCap || isWorkspaceCap ? "reset" : "recover";
     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");
+        ? `wait ~${humanWait(waitMs)} — ${windowPhrase} ${verb}s then`
+        : `wait for ${windowPhrase} to ${verb}`);
+    if (isKeyCap) {
+        // Deliberately NOT "run `cruxy login` for a fresh key". A new credential
+        // would carry a new counter, which is cap evasion dressed up as
+        // troubleshooting — and the cap exists to bound a leaked key.
+        nextSteps.push("or ask an org admin to raise this key's spend cap — a plan upgrade does not lift a per-key ceiling");
+    }
+    else if (isWorkspaceCap) {
+        nextSteps.push("or ask an org admin to raise the workspace's spend cap — a plan upgrade does not lift it");
+    }
+    else {
+        // 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: window
-            ? `your ${window} Cruxy budget is exhausted`
-            : "your Cruxy budget is exhausted",
+        title: isKeyCap
+            ? "this API key's monthly spend cap is reached"
+            : isWorkspaceCap
+                ? "this workspace's monthly spend cap is reached"
+                : window
+                    ? `your ${window} Cruxy budget is exhausted`
+                    : "your Cruxy budget is exhausted",
         cause: scrubbedMessageOf(underlying),
         nextSteps,
         underlying,
         meta: err
             ? {
+                ...(ceiling !== undefined ? { ceiling } : {}),
                 ...(err.window !== undefined ? { window: err.window } : {}),
                 ...(err.resetAt !== undefined ? { resetAt: err.resetAt } : {}),
                 ...(err.miraAvailable !== undefined
@@ -1502,9 +1548,18 @@ export function agentIncomplete(info) {
  * {@link CruxyError}, or `null` if it isn't one. Order matters: specific
  * subclasses before the `ApiError` base.
  */
-export function classifyProviderError(underlying) {
-    if (underlying instanceof AuthError)
-        return authInvalid(underlying);
+export function classifyProviderError(underlying, ctx = {}) {
+    if (underlying instanceof AuthError) {
+        // An expired credential and a wrong one produce the SAME 401 — the auth gate
+        // refuses both without saying which, so that a prober cannot learn a key was
+        // ever valid. The expiry we recorded at login is the only evidence there is,
+        // and without it a user whose 90-day device login simply ran out is told to
+        // go check a key they never mistyped.
+        const lifetime = classifyCredentialLifetime(ctx.credentialExpiresAt?.(), ctx.now);
+        return lifetime.state === "expired"
+            ? authExpired(lifetime.expiresAt, underlying)
+            : authInvalid(underlying);
+    }
     if (underlying instanceof RateLimitError)
         return apiRateLimit(underlying);
     if (underlying instanceof OverloadedError)
@@ -1530,3 +1585,27 @@ export function classifyProviderError(underlying) {
         return apiError(underlying);
     return null;
 }
+/**
+ * The typed pool denial behind an error, or `null` if it is not one.
+ *
+ * LIVES HERE BECAUSE IT HAS TWO CALLERS (cli#245). It was written for the
+ * fan-out seam (cli#243) and is needed byte-for-byte by the background-job
+ * executor, which flattened the same 429 into a message string and lost
+ * `window`, `resetAt` and `miraAvailable` — the three fields that make a denial
+ * actionable, and the last of which is the only one that unblocks someone now.
+ * A second copy of this in `jobs/` would be two places that decide what a pool
+ * denial is, and they would disagree the first time the SDK grows a class.
+ *
+ * Two shapes reach here and both are the same fact: the raw SDK
+ * `BudgetExhaustedError` from the run's own request, and — when a caller that
+ * already converted one re-throws — the {@link CruxyError} it produced. Mapping
+ * goes through {@link classifyProviderError} so there is still ONE place that
+ * knows which SDK class means what.
+ */
+export function poolDenial(err) {
+    if (CruxyError.is(err)) {
+        return err.code === ErrorCode.BudgetExhausted ? err : null;
+    }
+    const typed = classifyProviderError(err);
+    return typed?.code === ErrorCode.BudgetExhausted ? typed : null;
+}

package/dist/errors/types.js

@@ -32,6 +32,23 @@ export const ErrorCode = {
     // auth (exit 4)
     AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY",
     AuthInvalid: "CRUXY_E_AUTH_INVALID",
+    /**
+     * The stored credential's own lifetime has run out.
+     *
+     * A DISTINCT CODE FROM {@link AuthInvalid} because the two take opposite
+     * advice. "Your key is wrong" sends someone to check what they pasted; this
+     * one is a key that was right, worked for months, and reached the expiry the
+     * server stamped on it at login — the fix is to log in again, and telling that
+     * user to double-check their key sends them looking for a mistake they did not
+     * make.
+     *
+     * IT IS DECIDED CLIENT-SIDE, and it has to be. An expired key falls out of the
+     * auth gate's query exactly as a revoked or fabricated one does, and answers
+     * with the same bare 401 — deliberately, so a prober cannot learn that a key
+     * was ever valid. The server will never say "expired", so the only evidence is
+     * the expiry we stored when the credential was minted.
+     */
+    AuthExpired: "CRUXY_E_AUTH_EXPIRED",
     ForgeAuth: "CRUXY_E_FORGE_AUTH",
     /** A credential could not be persisted with owner-only permissions (C.27c) —
      * e.g. on Windows the store's ACL could not be restricted to the current user
@@ -296,6 +313,7 @@ const EXIT_CODES = {
     [ErrorCode.ConfigInvalid]: 3,
     [ErrorCode.AuthMissingKey]: 4,
     [ErrorCode.AuthInvalid]: 4,
+    [ErrorCode.AuthExpired]: 4,
     [ErrorCode.ForgeAuth]: 4,
     [ErrorCode.CredentialsUnprotected]: 4,
     [ErrorCode.GatewayUnreachable]: 5,

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { buildProgram } from "./cli/program.js";
+import { loadConfig, readCredentialMeta } from "./config/index.js";
 import { handleFatal, isCommanderSuccess, isVerbose } from "./errors/index.js";
 async function main() {
     const program = buildProgram();
@@ -12,5 +13,30 @@ main().catch((err) => {
     // with the raw stack shown only under --verbose.
     if (isCommanderSuccess(err))
         process.exit(0);
-    handleFatal(err, { verbose: isVerbose() });
+    handleFatal(err, {
+        verbose: isVerbose(),
+        context: {
+            // Resolved LAZILY — the classifier calls this only when the failure turns
+            // out to be a 401, so a run that fails any other way never reads config or
+            // the credentials store.
+            //
+            // It is needed because the gateway refuses an expired credential with
+            // exactly the 401 a wrong one gets, and deliberately will not say which.
+            // The expiry recorded at login is the only thing that can turn "your key
+            // is wrong" into "your login expired, run `cruxy login`".
+            //
+            // Wrapped, because this runs while we are already reporting a failure: an
+            // unreadable config or store here must not replace the user's real error
+            // with a crash inside the error handler.
+            credentialExpiresAt: () => {
+                try {
+                    const { config } = loadConfig();
+                    return readCredentialMeta(config.model.provider)?.expiresAt;
+                }
+                catch {
+                    return undefined;
+                }
+            },
+        },
+    });
 });