@cruxy/cli 1.7.0 → 1.8.0

package/dist/errors/constructors.js

@@ -1,4 +1,4 @@
-import { ApiError, AuthError, BudgetExhaustedError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { ApiError, AuthError, BudgetExhaustedError, InvalidRequestError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
 import { scrubModelNames } from "../brand/index.js";
 import { CruxyError, ErrorCode } from "./types.js";
 /**
@@ -199,6 +199,91 @@ export function apiError(underlying) {
         meta: status ? { status } : undefined,
     });
 }
+/**
+ * The gateway REJECTED what we sent (400/422) — it never reached a model.
+ *
+ * Everything else `classifyProviderError` produces says, in one wording or
+ * another, "wait and try again", because everything else IS a condition that
+ * passes. This one is not, and saying so is the entire point. The gateway parsed
+ * the request, found it invalid, and answered before any upstream call. The
+ * payload is built from this build's own code — the tool harness, the message
+ * shaping — so it is deterministic: a retry sends byte-identical content and
+ * earns a byte-identical refusal. There is no outage, nothing recovers on a
+ * clock, and no amount of patience helps.
+ *
+ * It follows that this is a DEFECT IN CRUXY and the only thing that fixes it is
+ * a code change. So the next steps say that instead of a soothing "retry in a
+ * 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.
+ */
+export function apiRequestRejected(underlying) {
+    const status = underlying instanceof ApiError ? underlying.status : undefined;
+    const cause = scrubbedMessageOf(underlying);
+    const tool = toolNamedIn(cause);
+    return new CruxyError({
+        code: ErrorCode.ApiRequestRejected,
+        title: tool
+            ? `the provider rejected this request — the \`${tool}\` tool definition cruxy sent is invalid`
+            : "the provider rejected this request — cruxy sent something invalid",
+        cause,
+        nextSteps: [
+            // First, because it pre-empts the reflex the other API errors trained.
+            "retrying will NOT help: the same request would be sent again and refused identically",
+            "this is a defect in cruxy, not a provider outage — nothing recovers on its own",
+            tool
+                ? `report it at ${ISSUE_URL} with this code and the tool name \`${tool}\``
+                : `report it at ${ISSUE_URL} with this code and the cause line above`,
+        ],
+        underlying,
+        meta: {
+            ...(status !== undefined ? { status } : {}),
+            ...(tool !== undefined ? { tool } : {}),
+        },
+    });
+}
+/**
+ * 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({
@@ -1433,6 +1518,14 @@ export function classifyProviderError(underlying) {
     if (underlying instanceof BudgetExhaustedError) {
         return budgetExhausted(underlying);
     }
+    // Also before the `ApiError` base. Without this arm a rejected request lands
+    // on the generic `apiError`, whose only next step is "retry in a moment; if it
+    // persists, check the provider's status" — advice that is wrong twice over for
+    // a 400: retrying re-sends the identical payload, and the provider's status
+    // page has nothing to say about a request it correctly refused.
+    if (underlying instanceof InvalidRequestError) {
+        return apiRequestRejected(underlying);
+    }
     if (underlying instanceof ApiError)
         return apiError(underlying);
     return null;

package/dist/errors/types.js

@@ -44,6 +44,18 @@ export const ErrorCode = {
     GitPushFailed: "CRUXY_E_GIT_PUSH_FAILED",
     // api (exit 6)
     Api: "CRUXY_E_API",
+    /**
+     * The gateway REJECTED the request (400/422) rather than failing to serve it.
+     *
+     * A DISTINCT CODE from {@link Api} because the two are opposite kinds of fact
+     * and take opposite advice. `Api` covers a provider that could not serve a
+     * valid request — a condition, which passes, so "retry in a moment" is sound.
+     * This one covers a request the gateway parsed, judged invalid, and refused
+     * before any upstream call. The payload is deterministic: a retry sends
+     * identical bytes and earns an identical refusal. Telling someone to wait out
+     * a rejection is telling them to wait for a defect in cruxy to fix itself.
+     */
+    ApiRequestRejected: "CRUXY_E_API_REQUEST_REJECTED",
     ApiRateLimit: "CRUXY_E_API_RATE_LIMIT",
     ApiOverloaded: "CRUXY_E_API_OVERLOADED",
     BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED",
@@ -289,6 +301,11 @@ const EXIT_CODES = {
     [ErrorCode.GatewayUnreachable]: 5,
     [ErrorCode.GitPushFailed]: 5,
     [ErrorCode.Api]: 6,
+    // Still the API exit class: the failure arrived from the gateway, and a script
+    // wrapping cruxy should treat it the same way it treats any other API failure.
+    // The difference this code carries is what a HUMAN should do about it, which
+    // is the next steps, not the exit status.
+    [ErrorCode.ApiRequestRejected]: 6,
     [ErrorCode.ApiRateLimit]: 6,
     [ErrorCode.ApiOverloaded]: 6,
     [ErrorCode.BudgetExhausted]: 6,

package/dist/indexing/walker.js

@@ -1,8 +1,13 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { globToRegexBody, isBinary } from "./util.js";
-/** Directories never descended into, regardless of ignore files. */
-const ALWAYS_IGNORE_DIRS = new Set([".git", "node_modules", ".cruxy"]);
+/**
+ * Directories never descended into, regardless of ignore files. Exported because
+ * `checkpoint/coverage.ts` pairs each name with the reason a checkpoint cannot
+ * restore what is under it — a name added here without a reason there fails the
+ * build, so the walker cannot quietly widen what the ceiling still calls safe.
+ */
+export const ALWAYS_IGNORE_DIRS = new Set([".git", "node_modules", ".cruxy"]);
 const DEFAULT_IGNORE_FILES = [".gitignore", ".cruxyignore"];
 /**
  * Hard denylist for secret-bearing files. Applied independently of ignore files

package/dist/limits/index.js

@@ -8,4 +8,4 @@
  * rendering lives in `tui/limits-panel.ts` — nothing here formats anything.
  */
 export { LimitsCache } from "./cache.js";
-export { reduceLimits, bindingWindow, usedFraction } from "./reduce.js";
+export { reduceLimits, bindingWindow, scarcestWindow, usedFraction, } from "./reduce.js";

package/dist/limits/reduce.js

@@ -144,15 +144,26 @@ export function reduceLimits(res, readAt = Date.now()) {
         readAt,
     };
 }
+/**
+ * TWO SELECTORS, TWO QUESTIONS. {@link bindingWindow} answers *which window will
+ * stop you first*; {@link scarcestWindow} answers *how much may you actually
+ * spend right now*. They are not the same question and they do not always pick
+ * the same window, so merging them would make one of the two answers wrong —
+ * see each function for which.
+ */
 /**
  * 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.
+ * FOR DISPLAY. 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.
+ *
+ * The fraction is right HERE because a bar is a fraction: the pixels state
+ * proportion, so the window drawn must be the one whose proportion is the
+ * warning. It is wrong for admission, and {@link scarcestWindow} says why.
  */
 export function bindingWindow(monthly, burst) {
     if (!monthly)
@@ -164,6 +175,37 @@ export function bindingWindow(monthly, burst) {
         ? { window: burst, name: "burst" }
         : { window: monthly, name: "month" };
 }
+/**
+ * The window with the least ABSOLUTE remaining — the ceiling an admission check
+ * must respect (cli#212).
+ *
+ * FOR ADMISSION. BOTH windows gate every request, so a draw of D is admitted
+ * only when `D ≤ monthly.remaining` AND `D ≤ burst.remaining` — which makes the
+ * spendable allowance exactly `min(remaining)`, a number of tokens rather than
+ * a proportion.
+ *
+ * WHY {@link bindingWindow} CANNOT SERVE HERE, concretely: a Core user 5% into
+ * the month (700k of 14M left) whose burst is at 14% (500k of 3.5M left). The
+ * fraction rule names the month, correctly — 5% is the figure worth showing.
+ * But handing 700k to an admission check authorises a batch the burst will
+ * refuse at 500k, and it refuses it AFTER the tokens are spent, against a
+ * sliding window that refills only by trickle over twelve hours. The two rules
+ * disagree exactly when the caps differ by 4×, which is to say on every
+ * self-serve tier, in the ordinary case rather than a corner one.
+ *
+ * The error is one-directional, which is why it is worth two functions: erring
+ * toward the smaller remainder narrows a fan-out that might have fitted, and
+ * erring toward the larger one spends a window that cannot be un-spent.
+ */
+export function scarcestWindow(monthly, burst) {
+    if (!monthly)
+        return burst ? { window: burst, name: "burst" } : undefined;
+    if (!burst)
+        return { window: monthly, name: "month" };
+    return burst.remaining < monthly.remaining
+        ? { 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))

package/dist/mcp/bounds.js

@@ -1,3 +1,4 @@
+import { MAX_SCHEMA_DEPTH, schemaDepth } from "../tools/schema-depth.js";
 const PERMISSIVE_SCHEMA = {
     type: "object",
     additionalProperties: true,
@@ -5,9 +6,16 @@ const PERMISSIVE_SCHEMA = {
 /**
  * Apply the bounds to a raw `tools/list`. Over the count cap → keep the first N
  * (by advertised order) and report `droppedCount`. Per tool: an over-long
- * description is truncated with a marker; an over-size input schema is replaced
- * with a permissive `object` schema and a note (we never forward an unbounded
- * schema, but we also never claim the args are constrained when we dropped it).
+ * description is truncated with a marker; an over-size OR over-deep input schema
+ * is replaced with a permissive `object` schema and a note (we never forward an
+ * unbounded or unsendable schema, but we also never claim the args are
+ * constrained when we dropped it).
+ *
+ * Degrading beats dying, and it is the same trade the byte cap already makes: an
+ * over-deep tool stays callable with unconstrained args and a visible note,
+ * rather than taking the session down with it. Nothing is lost locally by the
+ * swap — the adapter delegates arg validation to the server either way
+ * (`PASSTHROUGH`), and the approval gate is untouched.
  */
 export function boundToolList(tools, bounds) {
     const kept = tools.slice(0, bounds.maxTools);
@@ -30,6 +38,16 @@ export function boundToolList(tools, bounds) {
             inputSchema = { ...PERMISSIVE_SCHEMA };
             notes.push(`input schema (${schemaBytes} bytes) exceeded the ${bounds.maxSchemaBytes}-byte cap and was replaced with a permissive one`);
         }
+        // ORDER MATTERS: depth is measured on the POST-byte-cap value. A schema the
+        // byte cap already replaced is permissive (depth 1) and passes trivially, so
+        // the only schema this counter ever walks is one that fit `maxSchemaBytes` —
+        // which is what bounds the walk. Measuring the raw schema first would hand a
+        // hostile server an unbounded one.
+        const depth = schemaDepth(inputSchema);
+        if (depth >= MAX_SCHEMA_DEPTH) {
+            inputSchema = { ...PERMISSIVE_SCHEMA };
+            notes.push(`input schema nests ${depth} levels deep, at or over the ${MAX_SCHEMA_DEPTH}-level provider limit, and was replaced with a permissive one`);
+        }
         return { name: t.name, description, inputSchema, notes };
     });
     return { tools: bounded, droppedCount };

package/dist/plan/policy.js

@@ -5,11 +5,23 @@
  * for the rest of the run, recording the real scope in the shared
  * {@link SessionAllowlist} so U.3's own scoping (`scopeCovers`) governs reuse.
  *
- * What it deliberately does NOT do — the two-tier boundary:
+ * What it deliberately does NOT do — the boundary, in three parts:
  *   • **destructive** actions always fall through to the base policy (prompt);
  *   • **ungrantable** actions (`scope:"none"`) always fall through (prompt),
  *     even if the tier is `mutate` — because `SessionAllowlist.grant` is a no-op
- *     on `none`, an ungrantable action can never be pre-approved.
+ *     on `none`, an ungrantable action can never be pre-approved;
+ *   • **irreversible** actions always fall through (prompt), even if the tier is
+ *     `mutate` AND the scope is grantable (cli#193). This is the only one of the
+ *     three that `tier` cannot express: a write to `/etc/passwd` is tier
+ *     `mutate` with a perfectly good exact-file scope, and the checkpoint still
+ *     cannot restore it. Without this clause, "approve + allow safe steps"
+ *     silently authorized exactly that for the rest of the run.
+ *
+ * That last clause is why it is checked HERE rather than left to the allowlist.
+ * The ceiling in `SessionAllowlist.allows` covers grants being *spent*; this
+ * branch never asks `allows()` — it is pre-consent, so it *writes* a grant. It
+ * is the one path into the allowlist that the chokepoint cannot defend, so it
+ * carries its own copy of the same rule.
  *
  * So approving a plan (even with "allow safe steps") never consents to a
  * destructive or irreversible action; those re-confirm at execution time.
@@ -27,14 +39,18 @@ export class PlanExecutionPolicy {
         this.safeStepGrants = true;
     }
     async decide(request) {
-        // Already covered by a prior session grant (scoped, tier-keyed) → allow.
+        // Already covered by a prior session grant (scoped, tier-keyed, and — since
+        // cli#193 — reversible; `allows` enforces the ceiling itself) → allow.
         if (this.allowlist.allows(request))
             return { allow: true };
-        // The one plan-mode shortcut: a grantable mutate action, pre-consented by
-        // the "allow safe steps" choice. Record its concrete scope, then allow.
+        // The one plan-mode shortcut: a grantable, REVERSIBLE mutate action,
+        // pre-consented by the "allow safe steps" choice. Record its concrete scope,
+        // then allow. `!request.irreversible` is load-bearing, not defensive — see
+        // the third bullet in this class's doc comment.
         if (this.safeStepGrants &&
             request.tier === "mutate" &&
-            request.scope.kind !== "none") {
+            request.scope.kind !== "none" &&
+            !request.irreversible) {
             this.allowlist.grant(request);
             return { allow: true };
         }

package/dist/render/permissions-view.js

@@ -0,0 +1,88 @@
+import { fit, reflow, visibleWidth } from "./layout.js";
+/**
+ * The ceiling, in one line.
+ *
+ * Stated as an ABSOLUTE, because since cli#193 it is one: `allows()` checks
+ * `irreversible` before it matches any scope, so there is no longer a "unless
+ * you granted it" clause to add. #196 asked this screen to be honest about the
+ * asymmetry; the honest version today is that the asymmetry is closed, and the
+ * cost — a granted `git` not covering `git commit` — is what the inert marks
+ * and the re-prompt copy explain.
+ */
+const CEILING = "irreversible actions always ask — in every mode, and no session grant outranks it";
+/**
+ * How wide the label column may grow. A grant label is usually short (`git
+ * commands`, `changes under src/`), but an exact-file grant or a test grant
+ * carries a path or a whole command, and one long row must not cost every other
+ * row its tier and root.
+ */
+const LABEL_MAX_COLS = 34;
+/** `key  value`, on the same gutter `/status` uses so the two screens align. */
+function row(key, value, t) {
+    return `  ${t.muted(key.padEnd(11))} ${value}`;
+}
+/** `2 standing · 1 inert`, or what an empty/unwired list has to say instead. */
+function grantSummary(grants, t) {
+    if (!grants)
+        return t.muted("not tracked in this session");
+    if (grants.length === 0) {
+        return t.muted("none — every action has been decided one at a time");
+    }
+    const dead = grants.filter((g) => g.dead).length;
+    const live = grants.length - dead;
+    const head = `${live} standing`;
+    return dead === 0
+        ? head
+        : `${head} ${t.warning(`${t.glyph.sep} ${dead} inert`)}`;
+}
+/** The full `/permissions` block as lines to print. */
+export function permissionsReportLines(report, t, width = Infinity) {
+    const lines = [t.heading("permissions")];
+    lines.push(row("mode", `${t.strong(report.mode)} ${t.muted(`— ${report.modeDescription}`)}`, t));
+    // The ceiling is the one row that is the same in every session, and it is here
+    // for exactly that reason: a screen listing what runs without asking has to
+    // state what asks anyway, next to it, or the list reads as the whole answer.
+    lines.push(row("ceiling", report.autoApproves ? t.warning(CEILING) : t.muted(CEILING), t));
+    lines.push(row("grants", grantSummary(report.grants, t), t));
+    if (report.grants && report.grants.length > 0) {
+        lines.push("");
+        // One label column, sized to the longest label the list actually holds and
+        // capped so a pathological grant (a long exact path, a long test command)
+        // cannot push the tier and the root off a normal terminal. Padded on the
+        // VISIBLE width, because a coloured label carries escape bytes that
+        // `padEnd` would count and the terminal would not.
+        const labelCols = Math.min(LABEL_MAX_COLS, Math.max(...report.grants.map((g) => visibleWidth(g.label))));
+        for (const g of report.grants) {
+            const n = t.muted(`${g.n}`.padStart(2));
+            const text = fit(g.label, labelCols, t.glyph.ellipsis);
+            const pad = " ".repeat(Math.max(0, labelCols - visibleWidth(text)));
+            const label = g.dead ? t.muted(text) : t.strong(text);
+            lines.push(`  ${n}  ${label}${pad}  ${t.muted(`${g.tier} ${t.glyph.sep} ${g.where}`)}`);
+            if (!g.dead)
+                continue;
+            // Why it can never match, on its own rows so the reason survives a narrow
+            // terminal intact — an inert grant the user cannot read the reason for is
+            // the same puzzle as an unmarked one.
+            const indent = "      ";
+            const room = Number.isFinite(width)
+                ? Math.max(20, width - indent.length)
+                : Infinity;
+            const reason = `inert — ${g.dead}`;
+            const wrapped = Number.isFinite(room) ? reflow(reason, room) : [reason];
+            for (const line of wrapped)
+                lines.push(`${indent}${t.warning(line)}`);
+        }
+    }
+    lines.push("");
+    // THE SCOPE OF THE SCREEN. Every background job builds its own
+    // ApprovalService with its own allowlist, so a job's grants are neither
+    // listed here nor revoked by anything typed here. A permissions screen that
+    // implied otherwise would be understating what the session can still do.
+    lines.push(t.muted("this is the foreground session only — each background job keeps its own grants"));
+    if (report.grants && report.grants.length > 0) {
+        lines.push(t.muted("/permissions revoke <n> drops one — actions already decided keep their decision"));
+    }
+    return Number.isFinite(width)
+        ? lines.map((l) => fit(l, width, t.glyph.ellipsis))
+        : lines;
+}

package/dist/render/state.js

@@ -43,9 +43,28 @@ export function describePhase(phase, glyph = UNICODE_GLYPHS) {
             const base = t && t.input + t.output > 0
                 ? `thinking${e} ${glyph.sep} tokens ${glyph.caretUp}${formatTokens(t.input)} ${glyph.caretDown}${formatTokens(t.output)}`
                 : `thinking${e}`;
-            // The real routing tier (C.30), appended honestly when present — same
-            // ` · ` joiner as the token counts.
-            return phase.tier ? `${base} ${glyph.sep} ${phase.tier}` : base;
+            // The real routing tier (C.30) and the effort the gateway says it applied,
+            // appended honestly when present — same ` · ` joiner as the token counts.
+            //
+            // Order matters under truncation. `fitStatusLine`'s last resort clips the
+            // TAIL, so what is appended last is shed first: effort goes before the
+            // tier, which goes before the token counts, which go before "thinking…".
+            // That is the intended priority — the tier answers "what ran", effort only
+            // refines it.
+            //
+            // Effort is labelled rather than shown bare. `kavi · none` beside a tier
+            // name reads as a second tier; `kavi · effort none` cannot. The label
+            // costs seven columns and buys the line's only defence against being
+            // misread, which is worth more here than seven columns are.
+            const parts = [base];
+            if (phase.tier)
+                parts.push(phase.tier);
+            // A present `none` is the gateway SAYING no reasoning ran — a real answer
+            // to "what actually ran", and the one this readout exists to make
+            // visible. Absent stays absent; see ServedRouting.reasoningEffort.
+            if (phase.effort)
+                parts.push(`effort ${phase.effort}`);
+            return parts.join(` ${glyph.sep} `);
         }
         case "calling-tool":
             return `${phase.label}${e}`;