@cruxy/cli 1.8.1 → 1.10.0

package/dist/cli/session-factory.js

@@ -365,7 +365,8 @@ opts = {}) {
     const executionSemaphore = new Semaphore(config.subagent.maxConcurrency);
     // The ONE weighted-token budget for the whole session (P10 track 3 / cli#212).
     // `/budget` reads and sets it; `Session` narrows each turn's token guard by it;
-    // the orchestrator refuses to dispatch a fan-out it cannot cover. Three
+    // the orchestrator refuses to dispatch a fan-out (or a single spawn) it cannot
+    // cover; the job manager refuses a background job it cannot. Four
     // consumers, one object — a session cap and a fan-out bound that could disagree
     // would be the failure this exists to prevent. Its server denominator is
     // attached later (see `attachLimits`), because the limits cache does not exist
@@ -378,6 +379,21 @@ opts = {}) {
     // Outside `resumeLineAfterApproval`, so the live region is restored
     // before a preview block is committed into it.
     previewSilentApprovals(resumeLineAfterApproval((action) => approval.requestApproval(action), renderer), renderer), checkpoints, workspace), approvalMutex, cwd);
+    // THE LATE-BINDING HANDLE FOR THE SESSION BUILT AT THE END OF THIS FUNCTION.
+    //
+    // Declared here, above the first construction that needs it, rather than down
+    // beside the plan wiring it was written for. Three things now late-bind to the
+    // session — the approval policy's live mode read, and (cli#244) the job
+    // manager's session id — and the session cannot exist yet because it needs the
+    // ctx, the orchestrator and the job manager that are built between here and
+    // there.
+    //
+    // `autoApprove`: the policy has to read the LIVE mode, since the user can
+    // leave auto-approve between two actions of a single turn. Before the session
+    // exists there is nothing to approve, so the `false` fallback is a closed door
+    // rather than a gap.
+    const holder = {};
+    const autoApprove = () => holder.session?.getAutoApprove() ?? false;
     // Subagent orchestration (C.14): spawn_subagent goes on the main registry
     // only when depth allows (maxDepth 0 disables the feature structurally).
     // Registered before the plan wiring so plan-mode execution steps can
@@ -406,7 +422,6 @@ opts = {}) {
         makeChildApproval: () => gate(new ApprovalService({
             cwd,
             interactive: ttyInteractive,
-            io,
             policy: new InteractivePolicy(new SessionAllowlist(), io, autoApprove),
         })),
     });
@@ -432,6 +447,20 @@ opts = {}) {
             approvalMutex,
             foregroundInteractive: ttyInteractive,
             promptIO: io,
+            // The SAME budget the turn and the fan-out seam ask (cli#245). A job
+            // drawing on the weighted pool with no admission check was the last
+            // surface running `runAgent` that neither asked it nor moved it.
+            budget: sessionBudget,
+            // ...and the SAME usage sink the session's turns publish through
+            // (cli#244), so a job's spend is counted by `/usage` and not only by
+            // `/budget`. A job gets a record of its own because it can outlive the
+            // turn that launched it; see the note on `JobManagerDeps.onRunUsage`.
+            onRunUsage,
+            // Read lazily: the session is constructed below and does not exist yet.
+            // Without this the job's record persists with no `sessionId` and is then
+            // invisible to in-session `/usage` and to `--session` — on disk, and
+            // unreadable by the two surfaces most likely to look for it.
+            sessionId: () => holder.session?.sessionId,
         })
         : undefined;
     const jobTool = jobManager ? makeRunInBackgroundTool(jobManager) : undefined;
@@ -465,19 +494,11 @@ opts = {}) {
     // One allowlist shared by the plan-approval prompt and the per-action gate, so
     // a grant recorded during execution is honored by U.3's own check.
     const allowlist = new SessionAllowlist();
-    // Late-bound to the session constructed below. The policy has to read the LIVE
-    // mode — the user can leave auto-approve between two actions of a single turn
-    // — and the session cannot exist yet because it needs the ctx this policy is
-    // wired into. Before it exists there is nothing to approve, so the `false`
-    // fallback is a closed door rather than a gap.
-    const holder = {};
-    const autoApprove = () => holder.session?.getAutoApprove() ?? false;
     const planPolicy = new PlanExecutionPolicy(allowlist, new InteractivePolicy(allowlist, io, autoApprove));
     const approval = new ApprovalService({
         cwd,
         interactive: ttyInteractive,
         policy: planPolicy,
-        io,
     });
     const ctx = {
         cwd,

package/dist/config/credential-lifetime.js

@@ -0,0 +1,42 @@
+/**
+ * How close a stored credential is to the end of its life — a pure function of a
+ * timestamp and a clock.
+ *
+ * IT LIVES IN ITS OWN MODULE, AND IMPORTS NOTHING, so that `errors/` can reach
+ * it. `config/credentials.ts` imports `errors/` (for the unprotected-store
+ * refusal), so an error constructor importing the credentials store back would
+ * close a cycle. The rule this module needs to state is not about the store at
+ * all — it is arithmetic on one timestamp — so it sits below both and each side
+ * imports it directly.
+ *
+ * ONE CLASSIFIER, because every caller that acts on expiry must reach the same
+ * verdict from the same value: the 401 classifier deciding whether to say "your
+ * key is wrong" or "your login expired", the pre-session nudge deciding whether
+ * to warn, and the limits panel deciding what to render. Three private
+ * `Date.parse` comparisons would be three chances to disagree about whether a
+ * credential is dead.
+ */
+/**
+ * How long before expiry a credential is worth mentioning.
+ *
+ * Seven days against the gateway's 90-day device-key lifetime: long enough that
+ * someone who uses cruxy weekly sees the notice at least once before anything
+ * breaks, short enough that it is not background noise for the other 83 days.
+ */
+export const CREDENTIAL_EXPIRY_WARNING_MS = 7 * 24 * 60 * 60 * 1000;
+export function classifyCredentialLifetime(expiresAt, now = Date.now(), warnWithinMs = CREDENTIAL_EXPIRY_WARNING_MS) {
+    if (expiresAt === undefined || expiresAt === "")
+        return { state: "unknown" };
+    const at = Date.parse(expiresAt);
+    // A timestamp this build cannot read is a thing we do not know, not a thing
+    // that has happened.
+    if (Number.isNaN(at))
+        return { state: "unknown" };
+    const msRemaining = at - now;
+    if (msRemaining <= 0)
+        return { state: "expired", expiresAt };
+    if (msRemaining <= warnWithinMs) {
+        return { state: "expiring", expiresAt, msRemaining };
+    }
+    return { state: "live", expiresAt, msRemaining };
+}

package/dist/config/credentials.js

@@ -3,8 +3,13 @@ import { dirname, join } from "node:path";
 import { CREDENTIALS_FILE_NAME } from "../constants.js";
 import { credentialsUnprotected } from "../errors/index.js";
 import { logger } from "../utils/logger.js";
+import { classifyCredentialLifetime, } from "./credential-lifetime.js";
 import { enforceOwnerOnly, isOwnerOnly } from "./owner-only.js";
 import { globalDir } from "./paths.js";
+// Re-exported so `config/index.js` remains the one import site for credential
+// concerns; the classifier itself lives in a leaf module that imports nothing,
+// because `errors/` needs it too and this file imports `errors/`.
+export { classifyCredentialLifetime, CREDENTIAL_EXPIRY_WARNING_MS, } from "./credential-lifetime.js";
 /**
  * The credentials store (U.6) — the one place a provider API key is persisted.
  * It lives **outside** `config.json` on purpose: config is secret-free by design
@@ -89,15 +94,76 @@ export function writeMcpCredential(ref, token, file = credentialsPath()) {
         store.mcp[ref] = token;
     }, "mcp");
 }
+/**
+ * What we know about the stored key for `provider`, or `undefined`.
+ *
+ * Tolerant of a store written by a newer build or corrupted by hand: an entry
+ * that is not an object, or whose fields are the wrong type, reads as absent
+ * rather than throwing. This backs an expiry warning, and a warning that can
+ * crash the CLI is worse than no warning. Never throws.
+ */
+export function readCredentialMeta(provider, file = credentialsPath()) {
+    const store = readStore(file);
+    const raw = store?.keyMeta?.[provider];
+    if (raw === null || typeof raw !== "object")
+        return undefined;
+    const entry = raw;
+    const meta = {};
+    if (typeof entry.expiresAt === "string" && entry.expiresAt !== "") {
+        meta.expiresAt = entry.expiresAt;
+    }
+    if (typeof entry.keyId === "string" && entry.keyId !== "") {
+        meta.keyId = entry.keyId;
+    }
+    if (entry.source === "device" || entry.source === "paste") {
+        meta.source = entry.source;
+    }
+    return meta;
+}
 /**
  * Persist `key` for `provider`, merging into any existing store. Written
  * owner-only (see {@link writeInto}); refuses loudly if that can't be enforced.
+ *
+ * A bare write CLEARS any metadata held for that provider, because a write with
+ * nothing to say about the key's lifetime is a statement that we do not know it.
+ * The alternative — leaving whatever was there — is the one way this store can
+ * lie: paste an eternal admin key over a slot a device login used, and the
+ * stale 90-day expiry would have us announce that a perfectly good credential
+ * had died. Key and metadata therefore only ever move together, through
+ * {@link writeCredentialWithMeta}.
  */
 export function writeCredential(provider, key, file = credentialsPath()) {
+    writeCredentialWithMeta(provider, key, {}, file);
+}
+/** Persist `key` for `provider` together with what is known about it. */
+export function writeCredentialWithMeta(provider, key, meta, file = credentialsPath()) {
     writeInto(file, (store) => {
         store.keys[provider] = key;
+        const entry = {};
+        if (meta.expiresAt)
+            entry.expiresAt = meta.expiresAt;
+        if (meta.keyId)
+            entry.keyId = meta.keyId;
+        if (meta.source)
+            entry.source = meta.source;
+        if (Object.keys(entry).length === 0) {
+            // Nothing known. Drop any prior entry rather than keeping a fact about
+            // a key that no longer exists in this slot.
+            if (store.keyMeta) {
+                delete store.keyMeta[provider];
+                if (Object.keys(store.keyMeta).length === 0)
+                    delete store.keyMeta;
+            }
+            return;
+        }
+        store.keyMeta ??= {};
+        store.keyMeta[provider] = entry;
     }, "provider");
 }
+/** The lifetime of the credential currently stored for `provider`. */
+export function credentialLifetime(provider, now = Date.now(), file = credentialsPath()) {
+    return classifyCredentialLifetime(readCredentialMeta(provider, file)?.expiresAt, now);
+}
 /**
  * Merge `mutate` into the store and persist it owner-only. The one write path
  * shared by every credential namespace, and the single place the owner-only

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/boundary.js

@@ -1,5 +1,5 @@
 import { CommanderError } from "commander";
-import { classifyProviderError, internal, usageError } from "./constructors.js";
+import { classifyProviderError, internal, usageError, } from "./constructors.js";
 import { shouldUseColor, terminalFormatter } from "./format.js";
 import { CruxyError } from "./types.js";
 /**
@@ -16,13 +16,13 @@ import { CruxyError } from "./types.js";
  * - a known provider/transport error → its mapped code;
  * - anything else → CRUXY_E_INTERNAL, preserving the original as `underlying`.
  */
-export function fromUnknown(err) {
+export function fromUnknown(err, ctx = {}) {
     if (err instanceof CruxyError)
         return err;
     if (err instanceof CommanderError) {
         return usageError(stripErrorPrefix(err.message));
     }
-    return classifyProviderError(err) ?? internal(err);
+    return classifyProviderError(err, ctx) ?? internal(err);
 }
 /** A Commander "error" that's actually success (`--help`, `--version`). */
 export function isCommanderSuccess(err) {
@@ -34,7 +34,7 @@ export function isCommanderSuccess(err) {
  * touching the real process.
  */
 export function handleFatal(err, opts = {}) {
-    const cruxy = fromUnknown(err);
+    const cruxy = fromUnknown(err, opts.context ?? {});
     const verbose = opts.verbose ?? isVerbose();
     const color = opts.color ?? shouldUseColor();
     const formatter = opts.formatter ?? terminalFormatter;