@cruxy/cli 1.9.0 → 1.10.0

package/dist/config/schema.js

@@ -2,7 +2,24 @@ import { z } from "zod";
 import { LOG_LEVELS } from "../utils/logger.js";
 import { MODEL_TIERS } from "../brand/voice.js";
 import { TASK_CLASSES } from "../routing/types.js";
-export const ProviderSchema = z.enum(["cruxy", "openai", "custom"]);
+/**
+ * The backends a session can run on. ONE, deliberately.
+ *
+ * This used to be `["cruxy", "openai", "custom"]`. Neither extra value could
+ * ever produce a working session: `createProvider` implements `cruxy` and
+ * throws {@link NotImplementedError} for anything else, so `provider: "openai"`
+ * passed config validation and then failed at session start — a promise the
+ * schema made and the SDK refused. `OpenAICompatibleProvider`, the only code
+ * that could have honoured it, was removed in #260; "reserved for the future"
+ * is not a claim this enum can support when the implementation it named is
+ * gone.
+ *
+ * Rejecting them HERE is the point: a bad provider is now a config-load error
+ * that names the valid values, instead of a NotImplementedError thrown after
+ * onboarding has already run. Adding a backend means adding the value back
+ * together with the provider that serves it — never ahead of it.
+ */
+export const ProviderSchema = z.enum(["cruxy"]);
 export const ModelConfigSchema = z
     .object({
     provider: ProviderSchema.default("cruxy"),
@@ -220,6 +237,73 @@ export const CheckpointConfigSchema = z
     retention: z.number().int().positive().default(10),
 })
     .strict();
+/**
+ * The floor under `sessions.retention`.
+ *
+ * The `--resume` picker (`PICKER_LIMIT`) and the TUI sidebar
+ * (`SIDEBAR_SESSIONS`) each offer ten rows. A retention below that would let
+ * both surfaces list sessions a later prune has already decided are
+ * expendable — offering a row and then deleting it is worse than never showing
+ * it. `session/retention-floor.test.ts` pins this against the two constants
+ * themselves, so raising either surface without raising the floor fails.
+ *
+ * Rejected rather than silently raised: a config that says 5 and behaves as 10
+ * is a config that lies, and `loadConfig` already treats a bad value as a hard
+ * error everywhere else.
+ */
+export const SESSION_RETENTION_FLOOR = 10;
+/**
+ * Session persistence and retention (#257).
+ *
+ * The stores either side of this one have always bounded themselves —
+ * checkpoints at 10, run history at 50 — and sessions did not. Every session
+ * file ever written was still on disk, and nothing could turn recording off.
+ *
+ * WHY AGE IS THE PRIMARY BOUND AND COUNT IS THE BACKSTOP. "Old sessions I will
+ * never resume" is how people actually think about this, and once a session
+ * that recorded nothing stops being written at all (the lazy-meta change that
+ * had to land first), every remaining file is a real conversation for which age
+ * is the honest signal. The count cap stays because age alone does not protect
+ * a directory where someone runs forty sessions a day.
+ *
+ * WHY NOT BYTES. `statSync` hands us the size for free, so cost is not the
+ * objection — meaning is. Pruning on bytes makes whether YOUR session survives
+ * depend on how chatty an unrelated one was, which is not a rule anyone can
+ * hold in their head. `cruxy sessions` reports bytes, because seeing where the
+ * disk went is exactly what a report is for; nothing prunes on them.
+ *
+ * PER PROJECT, matching `projectDir` and how listing already works. A global
+ * cap would need the cross-project scan #172 item 2 declined.
+ */
+export const SessionsConfigSchema = z
+    .object({
+    /**
+     * Master switch. When false nothing is recorded: no file, no `--resume`,
+     * no sidebar. The session runs entirely in memory.
+     */
+    enabled: z.boolean().default(true),
+    /**
+     * How many sessions to keep per project; older ones are pruned oldest-first.
+     * Never below {@link SESSION_RETENTION_FLOOR} — see the note there.
+     */
+    retention: z
+        .number()
+        .int()
+        .min(SESSION_RETENTION_FLOOR, {
+        message: `sessions.retention must be at least ${SESSION_RETENTION_FLOOR} — ` +
+            `the --resume picker and the TUI sidebar both offer that many rows, and ` +
+            `a lower retention would list sessions that are already marked for deletion`,
+    })
+        .default(50),
+    /**
+     * Prune sessions untouched for this many days. Measured on the file's
+     * MTIME, never on `meta.startedAt`: a conversation begun forty days ago and
+     * resumed this morning is live, and an age check on when it BEGAN would
+     * delete it out from under the user.
+     */
+    maxAgeDays: z.number().int().positive().default(30),
+})
+    .strict();
 /**
  * Test-execution loop (C.13): how the agent runs the project's test suite and
  * iterates on failures. The command is detected from package.json when unset;
@@ -517,7 +601,11 @@ export const UsageConfigSchema = z
  * arguments over the network (https + cert-validated + pinned to a public IP; http
  * only for a loopback dev server) and treats its responses as untrusted data. A
  * url's trust also binds its resolved IP set at trust time, so a later IP-set
- * change re-gates (weaker than a local binary fingerprint — see `mcp/types.ts`).
+ * change re-gates. NEITHER transport's fingerprint covers the server's CODE —
+ * both hash the invocation (command/args/env, url, credential ref, header names),
+ * so a trusted server that later ships different code is still trusted. Trust
+ * means "I accept running this", not "this is still what I trusted"; see
+ * `mcp/types.ts`.
  */
 export const McpServerSchema = z
     .object({
@@ -577,6 +665,40 @@ function isHttps(url) {
  * model names scrubbed, and results are NEVER persisted. The tool list a server
  * advertises is bounded (count + per-tool description/schema size) so a hostile
  * server can't blow the context budget.
+ *
+ * THE THREE BOUNDS HAVE CEILINGS OF THEIR OWN (#237). Each was `positive()` with
+ * no maximum, which made the protection exactly as good as the number the user
+ * typed: `maxSchemaBytes: 100000000` validated cleanly, and a cap whose docstring
+ * says a hostile server "can't flood context" then does not do that. The failure
+ * moved downstream to a provider request-size rejection or a blown context
+ * budget — a much worse place to find out than config load, where the answer is
+ * one line.
+ *
+ * These ceilings are a SANITY BOUND, NOT A PROTOCOL LIMIT, and the difference
+ * matters because `MAX_SCHEMA_DEPTH` (`tools/schema-depth.ts`) bounds the same
+ * schemas and is the opposite kind of number. That one mirrors a real gateway
+ * constraint: exceed it and the
+ * whole request fails, so it is not ours to choose and must never be raised to
+ * make a config work. These three mirror nothing upstream — no external validator
+ * enforces them and no request breaks at 65 KiB. They are a statement about what
+ * configuration is worth honoring, so they are picked to be obviously generous
+ * (8x, 16x, and 8x the shipped defaults) rather than tight. Different numbers in
+ * the same spirit would be just as correct; having no number at all was not.
+ *
+ * Rejected rather than silently clamped, on `SESSION_RETENTION_FLOOR`'s rule: a
+ * config that says 100000000 and behaves as 65536 is a config that lies. The cost
+ * is that an over-ceiling value is a hard `loadConfig` error, and the schema is
+ * `.strict()`, so it fails the whole CLI rather than just MCP. That is affordable
+ * HERE and would not be everywhere: these keys are documented nowhere, are not
+ * env-settable, and `initConfig` writes the defaults — so every generated config
+ * passes, and `setValue` rejects an over-ceiling `cruxy config set` at the write
+ * with the path and the bound named. Contrast `UsageConfigSchema`, which refuses
+ * the same hard error for the opposite reason: those keys were a documented
+ * feature people really had set, so rejecting them would hand a working user a
+ * CLI that will not start.
+ *
+ * The two timeouts above are deliberately left unbounded: a long timeout costs
+ * patience rather than memory, and a user may have a legitimately slow server.
  */
 export const McpConfigSchema = z
     .object({
@@ -592,15 +714,24 @@ export const McpConfigSchema = z
     /** Fail a single `tools/call` if the server does not respond within this many
      * ms — the connection is kept, only the one call errors. */
     requestTimeout: z.number().int().positive().default(30000),
-    /** Max tools accepted from ONE server; extras are dropped with a visible note
-     * (a hostile server can't advertise thousands of tools to flood context). */
-    maxToolsPerServer: z.number().int().positive().default(32),
+    /**
+     * Max tools accepted from ONE server; extras are dropped with a visible note
+     * (a hostile server can't advertise thousands of tools to flood context).
+     *
+     * PER SERVER, which is not the number that decides the context budget. Ten
+     * trusted servers at the default advertise up to 320 tools between them, and
+     * nothing caps that sum — this bound stops one server flooding the list, not
+     * a large `servers` map adding up. Configuring many servers is a deliberate
+     * act with a visible cost, so it is bounded by the user rather than here.
+     */
+    maxToolsPerServer: z.number().int().positive().max(256).default(32),
     /** Max characters kept from a single tool's description; the rest is truncated
-     * with a visible marker. */
-    maxDescriptionChars: z.number().int().positive().default(1024),
+     * with a visible marker. A description past the 16 KiB ceiling is not one. */
+    maxDescriptionChars: z.number().int().positive().max(16_384).default(1024),
     /** Max bytes kept from a single tool's advertised JSON input schema; an
-     * over-cap schema is replaced with a permissive one and a visible note. */
-    maxSchemaBytes: z.number().int().positive().default(8192),
+     * over-cap schema is replaced with a permissive one and a visible note. One
+     * tool's schema at the 64 KiB ceiling is already ~16k tokens of context. */
+    maxSchemaBytes: z.number().int().positive().max(65_536).default(8192),
 })
     .strict();
 /**
@@ -660,6 +791,7 @@ export const CruxyConfigSchema = z
     index: IndexConfigSchema.default({}),
     lsp: LspConfigSchema.default({}),
     checkpoint: CheckpointConfigSchema.default({}),
+    sessions: SessionsConfigSchema.default({}),
     subagent: SubagentConfigSchema.default({}),
     jobs: JobsConfigSchema.default({}),
     test: TestConfigSchema.default({}),

package/dist/constants.js

@@ -26,8 +26,18 @@ export const CONFIG_FILE_NAME = "config.json";
 export const CREDENTIALS_FILE_NAME = "credentials.json";
 /** Onboarding state + completion marker under the global dir (U.6). */
 export const ONBOARDING_FILE_NAME = "onboarding.json";
-/** Where a user creates a Cruxy gateway key (printed during onboarding). */
-export const CREATE_KEY_URL = "https://app.cruxy.in";
+/**
+ * Where a user creates a Cruxy gateway key (printed during onboarding).
+ *
+ * `cruxy.ai`, not `app.cruxy.in` — the app moved and the old host now only
+ * `308`s here. Printed verbatim into the terminal, where a redirect buys
+ * nothing: a URL a user copies by hand or reads aloud should be the one that
+ * serves the page, and this one outlived the redirect that was covering for it.
+ *
+ * Deliberately NOT `api.cruxy.in`. The gateway did not move, and nothing in
+ * this package that names it should be changed alongside this.
+ */
+export const CREATE_KEY_URL = "https://cruxy.ai";
 /** Project-level config filenames, checked in order. */
 export const PROJECT_CONFIG_FILENAMES = [
     "cruxy.config.json",

package/dist/errors/constructors.js

@@ -1,4 +1,4 @@
-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
@@ -245,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
@@ -273,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({
@@ -1604,3 +1585,27 @@ export function classifyProviderError(underlying, ctx = {}) {
         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;
+}