kritya 0.8.24-beta → 0.8.25-beta

package/README.md

@@ -65,6 +65,9 @@ Requires Node.js >=22.
    - Linux/macOS: `export NVIDIA_API_KEY=nvapi-...`
    - Windows: `setx NVIDIA_API_KEY nvapi-...` (then open a new terminal)
 
+   Skip this and kritya will prompt for the key on first launch (interactive
+   mode only) and save it to `~/.kritya/.env` for you.
+
    Optional: add `TAVILY_API_KEY` the same way to enable the agent's
    web-search tool (`/web-search`) — get one at [tavily.com](https://tavily.com).
 
@@ -159,6 +162,7 @@ In-session commands (type `/` to see them with autocomplete; letters filter the
 | `/cost`                   | token usage and estimated $ (see Pricing below)                                                                                     |
 | `/audit`                  | show this session's permission decisions and verify the audit log's chain ([more](docs/CONFIGURATION.md#audit-log--telemetry))      |
 | `/budget`                 | show session token budget; `/budget reset` or `/budget <number>`                                                                    |
+| `/status`                 | show context/budget/token/task detail left off the always-visible status line                                                       |
 | `/kill`                   | emergency stop: `/kill [reason]` halts everything; `/kill off` releases                                                             |
 | `/help`                   | command list                                                                                                                        |
 | `/exit`                   | quit                                                                                                                                |
@@ -282,8 +286,8 @@ full tool output. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
   message is queued and absorbed before its next step (no need to interrupt).
 - **Auto-compaction → self-improving project memory** — when the conversation
   nears the model's context window (80% of `contextWindow`, default 120k
-  tokens), older turns are summarized automatically; the statusline shows
-  current usage as `ctx N%`. Compaction (auto or manual `/compact`) also
+  tokens), older turns are summarized automatically; `/status` shows current
+  usage as `context used: N%`. Compaction (auto or manual `/compact`) also
   distills durable, objective facts out of what's being summarized away —
   build/test commands, package manager, conventions actually observed — and
   merges any new ones into a `## Learned by kritya` section in `KRITYA.md`,
@@ -294,7 +298,8 @@ full tool output. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
 - **Token budget** — a session-wide cap on combined prompt + completion
   tokens across every turn and model (default 1,000,000; set `tokenBudget` in
   config, or `/budget <number>` mid-session). The statusline shows `budget N%`
-  once usage starts, turning yellow past 80% with a one-time warning, then
+  once usage crosses 80% (yellow, with a one-time warning) or the budget is
+  hit (red); `/status` shows it from the start. It then
   stops further turns entirely at 100% until you run `/budget reset` (clears
   the count) or `/budget <number>` (raises the cap). `/cost` also reports it.
 - **Background processes** — the agent can start dev servers/watchers with
@@ -311,7 +316,7 @@ full tool output. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
   every request.
 - **Sub-task checklist → resumable plans** — for multi-step requests the agent
   plans first and shows a live ☐/◐/☑ checklist as it works, with a compact
-  `tasks N/M` summary in the statusline. The checklist is saved alongside the
+  `tasks N/M` summary available via `/status`. The checklist is saved alongside the
   session, so `kritya -c` (and picking a session via `-r`) restores not just
   the conversation but exactly which steps were done, in progress, or still
   pending.
@@ -346,7 +351,7 @@ full tool output. `Ctrl+K` is the kill switch (see below). `Ctrl+C` exits.
 - **Prompt-caching awareness** — the system prompt is ordered stable-first
   (identity and rules → project memory → volatile git status/listing last) so
   providers can reuse their cached prompt prefix across turns instead of
-  re-reading everything. `/cost` and the statusline show how many prompt
+  re-reading everything. `/cost` and `/status` show how many prompt
   tokens were served from the provider's cache; add an optional
   `"cachedInput"` rate to your `pricing` config to see the dollar savings.
 - **LSP integration** — the agent gets go-to-definition, find-references,

package/dist/commands/registry.js

@@ -9,73 +9,138 @@ import { scanPluginMcpServers } from "../plugins/mcp.js";
 import { listProviders } from "../config/config.js";
 import { expandCommand } from "./custom.js";
 import { artifactPath, clearProjectState, loadProjectState, parseIdea, parsePhase, phaseBlocker, phasePrompt, renameProject, staleArtifacts, PHASE_COMMAND, PHASE_ORDER, PHASE_SUMMARY, saveProjectState, slugify, } from "../agent/workflow.js";
+const WORKFLOW = "Workflow";
+const SESSION = "Session";
+const SAFETY = "Safety & limits";
+const INFO = "Info";
 export const BUILTIN_COMMANDS = [
-    { name: "/help", description: "show available commands" },
-    { name: "/model", description: "pick a model, or /model <id> for any provider model ID" },
-    {
-        name: "/provider",
-        description: "list providers, or /provider <name> to switch mid-session (keeps history); add --default to persist",
-    },
     {
         name: "/flow-brainstorm",
         description: "start a new-project workflow: /flow-brainstorm <idea> (brainstorm→spec→plan→build→review→fix)",
+        category: WORKFLOW,
     },
     {
         name: "/flow-spec",
         description: "project workflow: write the spec from the approved brainstorm",
+        category: WORKFLOW,
+    },
+    {
+        name: "/flow-plan",
+        description: "project workflow: plan from the spec (read-only)",
+        category: WORKFLOW,
+    },
+    {
+        name: "/flow-build",
+        description: "project workflow: implement the plan, with tests",
+        category: WORKFLOW,
+    },
+    {
+        name: "/flow-review",
+        description: "project workflow: spec-compliance and security review",
+        category: WORKFLOW,
+    },
+    {
+        name: "/flow-fix",
+        description: "project workflow: fix the review's findings, re-verified",
+        category: WORKFLOW,
     },
-    { name: "/plan", description: "toggle plan mode: /plan, /plan on, /plan off" },
-    { name: "/flow-plan", description: "project workflow: plan from the spec (read-only)" },
-    { name: "/flow-build", description: "project workflow: implement the plan, with tests" },
-    { name: "/flow-review", description: "project workflow: spec-compliance and security review" },
-    { name: "/flow-fix", description: "project workflow: fix the review's findings, re-verified" },
     {
         name: "/project",
         description: "workflow status · /project goto <phase> · rename <name> · clear",
+        category: WORKFLOW,
     },
-    { name: "/diff", description: "show the cumulative git diff of this session's changes" },
-    { name: "/redo", description: "reapply the change most recently undone" },
-    { name: "/init", description: "scan the repo and generate a KRITYA.md project-memory file" },
-    { name: "/web-search", description: "search the web: /web-search <query>" },
     {
-        name: "/mcp",
-        description: "MCP servers: status, /mcp add|remove <name>, /mcp login|logout <name>",
+        name: "/model",
+        description: "pick a model, or /model <id> for any provider model ID",
+        category: SESSION,
     },
     {
-        name: "/skills",
-        description: "list discovered skills (project + user-global) and why any were skipped",
+        name: "/provider",
+        description: "list providers, or /provider <name> to switch mid-session (keeps history); add --default to persist",
+        category: SESSION,
     },
     {
-        name: "/plugins",
-        description: "list discovered Agent Plugins, what each contributes, and why any were skipped",
+        name: "/diff",
+        description: "show the cumulative git diff of this session's changes",
+        category: SESSION,
+    },
+    {
+        name: "/init",
+        description: "scan the repo and generate a KRITYA.md project-memory file",
+        category: SESSION,
     },
-    { name: "/undo", description: "revert the file changes from the agent's last turn" },
+    { name: "/web-search", description: "search the web: /web-search <query>", category: SESSION },
+    {
+        name: "/commit",
+        description: "have the agent stage and commit the current changes",
+        category: SESSION,
+    },
+    {
+        name: "/compact",
+        description: "summarize older conversation to free context space",
+        category: SESSION,
+    },
+    { name: "/clear", description: "start a fresh conversation", category: SESSION },
+    {
+        name: "/undo",
+        description: "revert the file changes from the agent's last turn",
+        category: SESSION,
+    },
+    { name: "/redo", description: "reapply the change most recently undone", category: SESSION },
     {
         name: "/checkpoint",
         description: "save a named point: /checkpoint <name> (no name lists saved ones)",
+        category: SESSION,
     },
     {
         name: "/rewind",
         description: "rewind the conversation and files to a checkpoint: /rewind <name>",
+        category: SESSION,
+    },
+    {
+        name: "/plan",
+        description: "toggle plan mode (read-only): /plan, /plan on, /plan off",
+        category: SAFETY,
+    },
+    {
+        name: "/kill",
+        description: "emergency stop: /kill [reason] halts everything · /kill off releases (Ctrl+K)",
+        category: SAFETY,
     },
-    { name: "/commit", description: "have the agent stage and commit the current changes" },
-    { name: "/compact", description: "summarize older conversation to free context space" },
-    { name: "/clear", description: "start a fresh conversation" },
-    { name: "/cost", description: "show token usage and estimated cost" },
     {
         name: "/audit",
         description: "show this session's permission decisions and verify the audit log's chain",
+        category: SAFETY,
     },
     {
         name: "/budget",
         description: "show session token budget, /budget reset, or /budget <number> to set it",
+        category: SAFETY,
     },
+    { name: "/cost", description: "show token usage and estimated cost", category: SAFETY },
     {
-        name: "/kill",
-        description: "emergency stop: /kill [reason] halts everything · /kill off releases (Ctrl+K)",
+        name: "/status",
+        description: "show context/budget/token/task detail left off the status line",
+        category: SAFETY,
+    },
+    { name: "/help", description: "show available commands", category: INFO },
+    {
+        name: "/skills",
+        description: "list discovered skills (project + user-global) and why any were skipped",
+        category: INFO,
+    },
+    {
+        name: "/plugins",
+        description: "list discovered Agent Plugins, what each contributes, and why any were skipped",
+        category: INFO,
+    },
+    {
+        name: "/mcp",
+        description: "MCP servers: status, /mcp add|remove <name>, /mcp login|logout <name>",
+        category: INFO,
     },
-    { name: "/exit", description: "leave" },
-    { name: "/quit", description: "leave" },
+    { name: "/exit", description: "leave", category: INFO },
+    { name: "/quit", description: "leave", category: INFO },
 ];
 export const HELP_TEXT = `Commands:
 ${BUILTIN_COMMANDS.map((c) => `  ${c.name.padEnd(14)} ${c.description}`).join("\n")}
@@ -379,6 +444,9 @@ const handlers = {
     "/cost": (ctx) => {
         ctx.addItem({ kind: "info", text: ctx.costReport() });
     },
+    "/status": (ctx) => {
+        ctx.addItem({ kind: "info", text: ctx.statusReport() });
+    },
     "/audit": (ctx) => {
         const audit = ctx.agent.audit;
         if (!audit) {
@@ -674,6 +742,7 @@ const ALLOWED_WHILE_KILLED = new Set([
     "/quit",
     "/audit",
     "/cost",
+    "/status",
     "/diff",
     "/budget",
     "/mcp",

package/dist/config/config.js

@@ -165,6 +165,7 @@ export function resolveProvider(config, override) {
         name,
         baseUrl,
         apiKey,
+        apiKeyEnv: merged.apiKeyEnv,
         temperature: merged.temperature,
         topP: merged.topP,
         maxTokens: merged.maxTokens,
@@ -322,3 +323,17 @@ export function loadDotEnv(paths) {
         }
     }
 }
+/**
+ * Append one KEY=VALUE line to ~/.kritya/.env, creating the directory (and
+ * hardening its permissions) the same way saveConfig does for config.json.
+ * Used by the first-run API key setup prompt so a pasted key survives across
+ * restarts without the user having to edit a dotfile by hand.
+ */
+export function appendGlobalEnvVar(name, value) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+    hardenWindowsDir(CONFIG_DIR);
+    const envFile = path.join(CONFIG_DIR, ".env");
+    const sanitized = value.replace(/[\r\n]/g, "");
+    fs.appendFileSync(envFile, `${name}=${sanitized}\n`, { mode: 0o600 });
+    fs.chmodSync(envFile, 0o600);
+}

package/dist/config/models.js

@@ -76,3 +76,13 @@ export function modelDisplaySlug(modelId) {
         .replace(/^-+|-+$/g, "");
     return `${prefix}${slug}`;
 }
+/**
+ * "provider/model" for display, without the doubled prefix that comes from
+ * naively joining them: several providers' model IDs already carry their own
+ * namespace (NVIDIA's catalog is "nvidia/nemotron-...", so the "nvidia"
+ * provider plus that model id would otherwise print "nvidia/nvidia/...").
+ * Only skip the provider prefix when the model id already starts with it.
+ */
+export function displayModelId(providerName, modelId) {
+    return modelId.startsWith(`${providerName}/`) ? modelId : `${providerName}/${modelId}`;
+}

package/dist/headless.js

@@ -5,7 +5,7 @@ import { CONFIG_DIR, legacyGlobalModel, listProviders, loadConfig, loadDotEnv, p
 import { DEFAULT_MODEL, contextWindowFor } from "./config/models.js";
 import { PermissionManager } from "./permissions/permissions.js";
 import { loadRules } from "./permissions/rules.js";
-import { ProviderClient, RetryExhaustedError } from "./provider/client.js";
+import { ProviderClient, RetryExhaustedError, friendlyProviderErrorHint, } from "./provider/client.js";
 import { createSwitchyardClient } from "./provider/switchyardClient.js";
 import { SWITCHYARD_ROUTE_ID, resolveEffectiveModel, staleSwitchyardModelWarning, stopSwitchyardSidecar, } from "./provider/switchyardSidecar.js";
 import { SessionStore } from "./session/store.js";
@@ -257,7 +257,9 @@ export async function runHeadless(args) {
             errorMessage = `Stopped (${err.killReason ?? "kill switch engaged"})`;
         }
         else {
-            errorMessage = err instanceof Error ? err.message : String(err);
+            const message = err instanceof Error ? err.message : String(err);
+            const friendlyHint = friendlyProviderErrorHint(err, provider.name);
+            errorMessage = friendlyHint ? `${friendlyHint} (${message})` : message;
         }
     }
     finally {

package/dist/index.js

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { render } from "ink";
 import { Agent } from "./agent/loop.js";
-import { CONFIG_DIR, legacyGlobalModel, loadConfig, loadDotEnv, privacyModeFor, resolveProvider, } from "./config/config.js";
+import { CONFIG_DIR, appendGlobalEnvVar, legacyGlobalModel, loadConfig, loadDotEnv, privacyModeFor, resolveProvider, } from "./config/config.js";
 import { DEFAULT_MODEL, contextWindowFor } from "./config/models.js";
 import { PermissionManager } from "./permissions/permissions.js";
 import { loadRules } from "./permissions/rules.js";
@@ -26,6 +26,7 @@ import { UndoStack } from "./undo/undo.js";
 import { App } from "./ui/App.js";
 import { TrustPrompt } from "./ui/TrustPrompt.js";
 import { AiDisclosurePrompt } from "./ui/AiDisclosurePrompt.js";
+import { ApiKeySetupPrompt } from "./ui/ApiKeySetupPrompt.js";
 import { McpTrustPrompt } from "./ui/McpTrustPrompt.js";
 import { loadHooks, HookRunner } from "./hooks/hooks.js";
 import { loadMcpTools, shutdownMcp, } from "./mcp/client.js";
@@ -35,6 +36,7 @@ import { pluginsDir, scanPlugins, userPluginsDir } from "./plugins/discover.js";
 import { loadPluginMcpServers } from "./plugins/mcp.js";
 import { describeGatedContent, gatedContentHash, isTrusted, saveTrust } from "./trust/trust.js";
 import { isAiDisclosureShown, markAiDisclosureShown } from "./trust/aiDisclosure.js";
+import { isBannerSeen, markBannerSeen } from "./trust/bannerSeen.js";
 import { partitionByTrust, serverFingerprint, trustServer } from "./trust/mcpTrust.js";
 import { runHeadless } from "./headless.js";
 import { installCrashHandlers } from "./crash.js";
@@ -264,9 +266,27 @@ async function showAiDisclosureNotice() {
             } }));
     });
 }
+/**
+ * Interactive fallback when no API key resolved for the active provider.
+ * Lets the user paste one straight in, saving it to ~/.kritya/.env, rather
+ * than forcing them out to read env-var instructions and relaunch. Only
+ * called from the interactive TTY path (see main() below) — headless mode
+ * (src/headless.ts) never imports this and keeps failing with a plain error.
+ */
+async function promptApiKeySetup(providerName, envVarName) {
+    if (!envVarName)
+        return null;
+    return new Promise((resolve) => {
+        const instance = render(_jsx(ApiKeySetupPrompt, { providerName: providerName, envVarName: envVarName, onDecision: (result) => {
+                instance.unmount();
+                resolve(result.action === "save" ? result.key : null);
+            } }));
+    });
+}
 async function main() {
     const config = loadConfig();
     const privacyMode = args.privacy || privacyModeFor(config);
+    const firstLaunch = !isBannerSeen(workspace);
     if (!isAiDisclosureShown(workspace)) {
         await showAiDisclosureNotice();
         markAiDisclosureShown(workspace);
@@ -279,7 +299,15 @@ async function main() {
         loadDotEnv([path.join(workspace, ".env")]);
     }
     const provider = resolveProvider(config, args.provider || undefined);
-    const apiKey = provider.apiKey;
+    let apiKey = provider.apiKey;
+    if (!apiKey) {
+        const entered = await promptApiKeySetup(provider.name, provider.apiKeyEnv);
+        if (entered) {
+            appendGlobalEnvVar(provider.apiKeyEnv, entered);
+            process.env[provider.apiKeyEnv] = entered;
+            apiKey = entered;
+        }
+    }
     if (!apiKey) {
         const hint = provider.name === "nvidia"
             ? `Get one at https://build.nvidia.com, then one of:\n` +
@@ -687,5 +715,6 @@ async function main() {
             permissionRef.current = fn;
         }, onRequestElicitationReady: (fn) => {
             elicitationRef.current = fn;
-        }, privacyMode: privacyMode }));
+        }, privacyMode: privacyMode, firstLaunch: firstLaunch }));
+    markBannerSeen(workspace);
 }

package/dist/provider/client.js

@@ -99,6 +99,25 @@ export function isRetryable(err) {
     }
     return false;
 }
+/**
+ * A short, actionable translation for the non-retryable failures a
+ * first-time user is most likely to hit — a rejected key or an unknown
+ * model id — instead of the raw `{"status":403,"title":"Forbidden",...}`
+ * body the provider sent. Returns undefined for anything else, so callers
+ * fall back to the raw message unchanged.
+ */
+export function friendlyProviderErrorHint(err, providerName) {
+    const status = err?.status;
+    if (status === 401 || status === 403) {
+        return (`Your API key for provider "${providerName}" was rejected. Check it's correct, ` +
+            `still active, and hasn't expired, then try again.`);
+    }
+    if (status === 404 && !isEmptyBodyNotFound(err)) {
+        return (`Provider "${providerName}" doesn't recognize this model. Check the model ID with ` +
+            `/model, or that your account has access to it.`);
+    }
+    return undefined;
+}
 /** Read one header case-insensitively from whatever shape the SDK attached. */
 function headerValue(err, name) {
     const headers = err?.headers;

package/dist/trust/bannerSeen.js

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONFIG_DIR } from "../config/config.js";
+import { hardenWindowsDir } from "../config/winAcl.js";
+import { debugLog } from "../config/debug.js";
+/**
+ * Tracks which workspaces have already shown the full ASCII banner once, so
+ * repeat launches (which cost real vertical space in a terminal) can fall
+ * back to a compact one-line header instead. Same shape and persistence
+ * pattern as aiDisclosure.ts's ai-disclosure.json.
+ */
+const BANNER_FILE = path.join(CONFIG_DIR, "banner-seen.json");
+function loadStore(storeFile) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(storeFile, "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch (err) {
+        // A missing file means "not shown anywhere yet" (normal); a malformed one
+        // means every workspace re-shows the full banner, worth being able to see.
+        debugLog(`loadStore(${storeFile})`, err);
+        return {};
+    }
+}
+/** Whether the full ASCII banner has already been shown for this workspace. */
+export function isBannerSeen(workspace, storeFile = BANNER_FILE) {
+    return typeof loadStore(storeFile)[path.resolve(workspace)] === "string";
+}
+/** Record that the full ASCII banner has been shown for this workspace, now. */
+export function markBannerSeen(workspace, storeFile = BANNER_FILE) {
+    const store = loadStore(storeFile);
+    store[path.resolve(workspace)] = new Date().toISOString();
+    fs.mkdirSync(path.dirname(storeFile), { recursive: true, mode: 0o700 });
+    hardenWindowsDir(path.dirname(storeFile));
+    fs.writeFileSync(storeFile, JSON.stringify(store, null, 2) + "\n", { mode: 0o600 });
+}

package/dist/ui/ApiKeySetupPrompt.js

@@ -0,0 +1,22 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useState } from "react";
+import { Box, Text, useInput } from "ink";
+import TextInput from "ink-text-input";
+/**
+ * Shown once, only when the active provider has no API key resolved, on the
+ * interactive TTY path (never from headless — see runHeadless in
+ * src/headless.ts, which never imports this component). Lets a first-time
+ * user paste a key instead of hunting through env-var/dotfile instructions.
+ */
+export function ApiKeySetupPrompt({ providerName, envVarName, onDecision, }) {
+    const [value, setValue] = useState("");
+    useInput((_input, key) => {
+        if (key.escape)
+            onDecision({ action: "skip" });
+    });
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: "cyan", paddingX: 1, children: [_jsxs(Text, { bold: true, color: "cyan", children: ["No API key found for provider \"", providerName, "\""] }), _jsxs(Text, { children: ["Paste your ", envVarName, " value below to save it to ~/.kritya/.env and continue \u2014 or press Esc to skip and set it up yourself."] }), _jsxs(Box, { marginTop: 1, children: [_jsx(Text, { color: "cyan", children: "> " }), _jsx(TextInput, { value: value, onChange: setValue, mask: "*", onSubmit: (v) => {
+                            const trimmed = v.trim();
+                            if (trimmed)
+                                onDecision({ action: "save", key: trimmed });
+                        } })] })] }));
+}

package/dist/ui/App.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { Fragment, useCallback, useEffect, useRef, useState } from "react";
 import { Box, Static, Text, useApp, useInput, useStdout } from "ink";
 import TextInput from "ink-text-input";
 import fs from "node:fs";
@@ -30,7 +30,7 @@ const IMAGE_RE = /\.(png|jpe?g|gif|webp|bmp)$/i;
 // Erase screen + scrollback, then home the cursor (same sequence Ink itself
 // uses for its own "content taller than the terminal" clear path).
 const CLEAR_TERMINAL = "\x1b[2J\x1b[3J\x1b[H";
-export function App({ agent, workspace, modelRef, providerRef, config, resumedCount, initialTasks, undoStack, uiBridge, resumeSessions, customCommands = [], mcpToolCount = 0, onSwitchClient, onRequestPermissionReady, onRequestElicitationReady, privacyMode, }) {
+export function App({ agent, workspace, modelRef, providerRef, config, resumedCount, initialTasks, undoStack, uiBridge, resumeSessions, customCommands = [], mcpToolCount = 0, onSwitchClient, onRequestPermissionReady, onRequestElicitationReady, privacyMode, firstLaunch, }) {
     const { exit } = useApp();
     const { stdout } = useStdout();
     const [input, setInput] = useState("");
@@ -137,6 +137,7 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
         resumeSessions,
         refreshFileList,
         onSwitchClient,
+        firstLaunch,
     });
     useEffect(() => {
         onRequestPermissionReady?.(requestPermission);
@@ -154,11 +155,49 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
         const t = setInterval(() => setElapsed(Math.floor((Date.now() - start) / 1000)), 1000);
         return () => clearInterval(t);
     }, [phase]);
+    // Detail moved out of the always-visible status line (see StatusLine.tsx) —
+    // surfaced instead via the /status command, on demand.
+    const statusReport = useCallback(() => {
+        const sandboxActive = (config.sandboxExec ?? defaultSandboxMode()) !== "off" && sandboxAvailable();
+        const cachedPct = (totalUsage.cachedPromptTokens ?? 0) > 0
+            ? ` (${Math.round(((totalUsage.cachedPromptTokens ?? 0) / totalUsage.promptTokens) * 100)}% cached)`
+            : "";
+        const lines = [
+            `workspace: ${workspace}`,
+            `sandbox: ${sandboxActive ? "active" : "inactive"}`,
+            `context used: ${ctxPct}%`,
+            `token budget: ${budgetPct}% of ${tokenBudget.toLocaleString()} (${budgetUsed.toLocaleString()} used)${budgetStopped ? " — stopped" : ""}`,
+            `tokens: ${totalUsage.estimated ? "~" : ""}${totalUsage.promptTokens.toLocaleString()} in${cachedPct} / ${totalUsage.completionTokens.toLocaleString()} out`,
+            tasks.length > 0
+                ? `tasks: ${tasks.filter((t) => t.status === "done").length}/${tasks.length} done`
+                : null,
+            phase === "working" && elapsed > 0 ? `elapsed: ${elapsed}s` : null,
+            verbose ? "verbose: on" : null,
+        ].filter((l) => l !== null);
+        return lines.join("\n");
+    }, [
+        config,
+        workspace,
+        ctxPct,
+        budgetPct,
+        tokenBudget,
+        budgetUsed,
+        budgetStopped,
+        totalUsage,
+        tasks,
+        phase,
+        elapsed,
+        verbose,
+    ]);
     const allCommands = [
         ...BUILTIN_COMMANDS,
-        ...customCommands.map((c) => ({ name: c.name, description: c.description })),
+        ...customCommands.map((c) => ({
+            name: c.name,
+            description: c.description,
+            category: "Custom",
+        })),
         // Servers can contribute slash commands too (MCP prompts).
-        ...mcpPrompts().map((p) => ({ name: p.command, description: p.description })),
+        ...mcpPrompts().map((p) => ({ name: p.command, description: p.description, category: "MCP" })),
     ];
     // Command suggestions while typing a slash command (before any arguments).
     const suggestions = phase === "input" && input.startsWith("/") && !input.includes(" ")
@@ -308,6 +347,7 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
             runWebSearch,
             expandMentions,
             costReport,
+            statusReport,
             gitDiffStat,
             exit,
         };
@@ -445,7 +485,18 @@ export function App({ agent, workspace, modelRef, providerRef, config, resumedCo
                                     setInput((prev) => (isCtrlEcho(prev, v) ? prev : v.replace(/\t/g, "")));
                                     setCmdIndex(0);
                                     setFileIndex(0);
-                                }, onSubmit: handleSubmit }, inputKey)] }), suggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [suggestions.map((c, i) => (_jsxs(Text, { color: i === selectedCmd ? "cyan" : undefined, children: [i === selectedCmd ? "❯ " : "  ", _jsx(Text, { bold: i === selectedCmd, children: c.name }), _jsxs(Text, { dimColor: true, children: [" \u2014 ", c.description] })] }, c.name))), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter select \u00B7 Enter again to run" })] })), fileSuggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [fileSuggestions.map((f, i) => (_jsxs(Text, { color: i === selectedFile ? "cyan" : undefined, children: [i === selectedFile ? "❯ " : "  ", f] }, f))), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter attach file" })] }))] })), _jsx(Box, { children: _jsx(StatusLine, { killed: killed, killReason: killReason, dryRunMode: dryRunMode, planMode: planMode, acceptEdits: acceptEdits, autoApprovedCount: autoApprovedCount, provider: provider, model: servedModel && servedModel !== model
+                                }, onSubmit: handleSubmit }, inputKey)] }), suggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [(() => {
+                                // Group headers only earn their keep once more than one
+                                // category is actually on screen — once typing has filtered
+                                // down to a single family, a lone header is just noise.
+                                const showHeaders = new Set(suggestions.map((c) => c.category)).size > 1;
+                                let lastCategory;
+                                return suggestions.map((c, i) => {
+                                    const showHeader = showHeaders && c.category !== lastCategory;
+                                    lastCategory = c.category;
+                                    return (_jsxs(Fragment, { children: [showHeader && _jsx(Text, { dimColor: true, children: c.category ?? "Other" }), _jsxs(Text, { color: i === selectedCmd ? "cyan" : undefined, children: [i === selectedCmd ? "❯ " : "  ", _jsx(Text, { bold: i === selectedCmd, children: c.name }), _jsxs(Text, { dimColor: true, children: [" \u2014 ", c.description] })] })] }, c.name));
+                                });
+                            })(), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter select \u00B7 Enter again to run" })] })), fileSuggestions.length > 0 && (_jsxs(Box, { flexDirection: "column", paddingLeft: 2, children: [fileSuggestions.map((f, i) => (_jsxs(Text, { color: i === selectedFile ? "cyan" : undefined, children: [i === selectedFile ? "❯ " : "  ", f] }, f))), _jsx(Text, { dimColor: true, children: "\u2191\u2193 select \u00B7 Tab/Enter attach file" })] }))] })), _jsx(Box, { children: _jsx(StatusLine, { killed: killed, killReason: killReason, dryRunMode: dryRunMode, planMode: planMode, acceptEdits: acceptEdits, autoApprovedCount: autoApprovedCount, provider: provider, model: servedModel && servedModel !== model
                         ? `${model}-${modelDisplaySlug(servedModel)}`
-                        : model, workflow: workflow, branch: branch, tasks: tasks, ctxPct: ctxPct, budgetPct: budgetPct, budgetStopped: budgetStopped, phase: phase, elapsed: elapsed, totalUsage: totalUsage, totalCost: totalCost, verbose: verbose, workspace: workspace, sandboxActive: (config.sandboxExec ?? defaultSandboxMode()) !== "off" && sandboxAvailable(), persistenceWarningCount: persistenceWarningCount, privacyMode: privacyMode }) })] }));
+                        : model, workflow: workflow, branch: branch, budgetPct: budgetPct, budgetStopped: budgetStopped, totalCost: totalCost, sandboxActive: (config.sandboxExec ?? defaultSandboxMode()) !== "off" && sandboxAvailable(), persistenceWarningCount: persistenceWarningCount, privacyMode: privacyMode }) })] }));
 }

package/dist/ui/Banner.js

@@ -50,7 +50,10 @@ function rowColor(row) {
     return `#${[r, g, b].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
 }
 const BETA_LABEL = "beta";
-export function Banner({ subtitle }) {
+export function Banner({ subtitle, compact }) {
+    if (compact) {
+        return (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { dimColor: true, children: subtitle }) }));
+    }
     const columns = terminalColumns(process.stdout);
     const wide = bannerLines("KRITYA", "░░");
     const narrow = bannerLines("KRITYA", "░");

package/dist/ui/StatusLine.js

@@ -1,16 +1,19 @@
 import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
 import { Text } from "ink";
-/** The single dim status bar pinned to the bottom of the screen. */
-export function StatusLine({ killed, killReason, dryRunMode, planMode, acceptEdits, autoApprovedCount, provider, model, workflow, branch, tasks, ctxPct, budgetPct, budgetStopped, phase, elapsed, totalUsage, totalCost, verbose, workspace, sandboxActive, persistenceWarningCount, privacyMode, }) {
+import { displayModelId } from "../config/models.js";
+/**
+ * The single dim status bar pinned to the bottom of the screen. Keeps only
+ * the fields worth glancing at on every render; everything else (context %,
+ * task checklist, elapsed time, token counts, workspace path, verbose flag)
+ * moved to the on-demand `/status` command — see CommandContext.statusReport
+ * in src/commands/registry.ts.
+ */
+export function StatusLine({ killed, killReason, dryRunMode, planMode, acceptEdits, autoApprovedCount, provider, model, workflow, branch, budgetPct, budgetStopped, totalCost, sandboxActive, persistenceWarningCount, privacyMode, }) {
     return (_jsxs(Text, { dimColor: true, children: [killed ? (_jsxs(Text, { bold: true, color: "red", children: ["\u26D4 KILLED", killReason ? ` (${killReason})` : "", " \u00B7", " "] })) : (""), _jsxs(Text, { color: dryRunMode || planMode ? "cyan" : acceptEdits ? "green" : undefined, children: ["mode:", " ", dryRunMode
                         ? "dry-run"
                         : planMode
                             ? "plan"
                             : acceptEdits
                                 ? `accept-edits (${autoApprovedCount} auto)`
-                                : "default", " · "] }), provider, "/", model, _jsxs(Text, { color: sandboxActive ? "green" : "red", children: [" ", "\u00B7 ", sandboxActive ? "🔒 sandbox:active" : "🔓 sandbox:inactive"] }), workflow ? (_jsxs(Text, { color: "magenta", children: [" ", "\u00B7 \u2691 ", workflow.name, ":", workflow.phase] })) : (""), branch ? ` · ⎇ ${branch}` : "", tasks.length > 0
-                ? ` · tasks ${tasks.filter((t) => t.status === "done").length}/${tasks.length}`
-                : "", ctxPct > 0 ? ` · ctx ${ctxPct}%` : "", budgetPct > 0 ? (_jsxs(Text, { color: budgetStopped ? "red" : budgetPct >= 80 ? "yellow" : undefined, children: [" ", "\u00B7 budget ", budgetPct, "%"] })) : (""), phase === "working" && elapsed > 0 ? ` · ${elapsed}s` : "", " \u00B7", " ", totalUsage.estimated ? "~" : "", "tokens: ", totalUsage.promptTokens.toLocaleString(), " in", (totalUsage.cachedPromptTokens ?? 0) > 0
-                ? ` (${Math.round(((totalUsage.cachedPromptTokens ?? 0) / totalUsage.promptTokens) * 100)}% cached)`
-                : "", " ", "/ ", totalUsage.completionTokens.toLocaleString(), " out", totalCost > 0 ? ` · $${totalCost.toFixed(4)}` : "", persistenceWarningCount > 0 ? (_jsxs(Text, { color: "yellow", children: [" \u00B7 \u26A0 persistence warnings: ", persistenceWarningCount] })) : (""), privacyMode ? _jsx(Text, { color: "cyan", children: " \u00B7 privacy:on" }) : "", verbose ? " · verbose" : "", " \u00B7 workspace: ", workspace] }));
+                                : "default", " · "] }), displayModelId(provider, model), _jsxs(Text, { color: sandboxActive ? "green" : "red", children: [" ", "\u00B7 ", sandboxActive ? "🔒 sandbox:active" : "🔓 sandbox:inactive"] }), workflow ? (_jsxs(Text, { color: "magenta", children: [" ", "\u00B7 \u2691 ", workflow.name, ":", workflow.phase] })) : (""), branch ? ` · ⎇ ${branch}` : "", budgetStopped || budgetPct >= 80 ? (_jsxs(Text, { color: budgetStopped ? "red" : "yellow", children: [" \u00B7 budget ", budgetPct, "%"] })) : (""), totalCost > 0 ? ` · $${totalCost.toFixed(4)}` : "", persistenceWarningCount > 0 ? (_jsxs(Text, { color: "yellow", children: [" \u00B7 \u26A0 persistence warnings: ", persistenceWarningCount] })) : (""), privacyMode ? _jsx(Text, { color: "cyan", children: " \u00B7 privacy:on" }) : "", " · /status for details"] }));
 }

package/dist/ui/TranscriptItem.js

@@ -9,5 +9,5 @@ export function TranscriptItem({ item, verbose, stdout }) {
     return (_jsxs(Box, { marginBottom: item.kind === "tool" ? 0 : 1, flexDirection: "column", children: [item.kind === "user" && (_jsxs(Text, { children: [_jsxs(Text, { bold: true, color: "green", children: ["\u276F", " "] }), item.text] })), item.kind === "assistant" && _jsx(Markdown, { text: item.text }), item.kind === "tool" && (_jsxs(Box, { flexDirection: "column", children: [_jsxs(Text, { dimColor: true, children: [item.error ? _jsx(Text, { color: "red", children: "\u2717" }) : _jsx(Text, { color: "green", children: "\u2713" }), " ", item.summary, item.resultSummary && !verbose ? ` — ${item.resultSummary}` : ""] }), item.output && item.output.trim() && (item.resultSummary === undefined || verbose) && (_jsx(Text, { dimColor: true, children: toolOutputPreview(item.output, verbose, Math.max(20, terminalColumns(stdout) - 6), item.error)
                             .split("\n")
                             .map((l) => `    ${l}`)
-                            .join("\n") }))] })), item.kind === "info" && _jsx(Text, { dimColor: true, children: item.text }), item.kind === "banner" && _jsx(Banner, { subtitle: item.subtitle })] }));
+                            .join("\n") }))] })), item.kind === "info" && _jsx(Text, { dimColor: true, children: item.text }), item.kind === "banner" && _jsx(Banner, { subtitle: item.subtitle, compact: item.compact })] }));
 }

package/dist/ui/useAgent.js

@@ -2,8 +2,8 @@ import { useCallback, useEffect, useRef, useState } from "react";
 import path from "node:path";
 import { gitBranch } from "../git/git.js";
 import { listProviders, resolveProvider, saveConfig, saveProviderModel, } from "../config/config.js";
-import { DEFAULT_MODEL, contextWindowFor } from "../config/models.js";
-import { ProviderClient, RetryExhaustedError } from "../provider/client.js";
+import { DEFAULT_MODEL, contextWindowFor, displayModelId } from "../config/models.js";
+import { ProviderClient, RetryExhaustedError, friendlyProviderErrorHint, } from "../provider/client.js";
 import { createSwitchyardClient } from "../provider/switchyardClient.js";
 import { SWITCHYARD_ROUTE_ID, resolveEffectiveModel } from "../provider/switchyardSidecar.js";
 import { KillSwitchError } from "../agent/killSwitch.js";
@@ -29,7 +29,7 @@ function initialToolStatus(name) {
  * permission state, usage/cost tracking, and session resume. Input handling
  * (text box, slash-command suggestions, @mention autocomplete) stays in App.
  */
-export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBridge, resumedCount, initialTasks, resumeSessions, refreshFileList, onSwitchClient, }) {
+export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBridge, resumedCount, initialTasks, resumeSessions, refreshFileList, onSwitchClient, firstLaunch, }) {
     const nextId = useRef(0);
     const [items, setItems] = useState(() => {
         const initial = [
@@ -37,6 +37,7 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
                 id: nextId.current++,
                 kind: "banner",
                 subtitle: `${path.basename(workspace)} · ${modelRef.current} · type a request, or /help for commands`,
+                compact: !firstLaunch,
             },
         ];
         if (resumedCount > 0) {
@@ -382,7 +383,7 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
             return;
         }
         setPhase("working");
-        setActivity(`Calling ${provider}/${model}…`);
+        setActivity(`Calling ${displayModelId(provider, model)}…`);
         const ac = new AbortController();
         abortRef.current = ac;
         setInFlight([]);
@@ -468,7 +469,8 @@ export function useAgent({ agent, workspace, modelRef, providerRef, config, uiBr
                     text = `Error: ${message}${hint}`;
                 }
                 else {
-                    text = `Error: ${message}`;
+                    const friendlyHint = friendlyProviderErrorHint(err, provider);
+                    text = friendlyHint ? `${friendlyHint}\n\n(${message})` : `Error: ${message}`;
                 }
             }
             addItem({ kind: "info", text });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kritya",
-  "version": "0.8.24-beta",
+  "version": "0.8.25-beta",
   "description": "Kritya — a lean, provider-agnostic terminal coding agent (NVIDIA, OpenAI, OpenRouter, Groq, Ollama, and more)",
   "type": "module",
   "publishConfig": {