@mafdet/cli 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -6,6 +6,49 @@ The version is the contract for the JSON output shapes and the exit codes.
 Being 0.x, semver still permits a break in a minor bump; the intent is not to
 use that latitude, and the promise becomes binding at 1.0.0.
 
+## 0.4.0 - 2026-08-07
+
+An interactive session. Running `mafdet` with no arguments in a terminal now
+opens one: choose how to authenticate, pick a model, then work with the agent.
+Everything else is unchanged; scripts are unaffected (see below).
+
+### The session
+
+- The welcome page, then authentication, then a model picker that narrows as
+  you type, then the agent.
+- Authentication offers only what the system can serve: the environment key, a
+  key pasted for this session only, or instructions for creating one. A pasted
+  key is held in memory, never written to a file and never put into the
+  environment.
+- The model picker lists only what this key can call. Where any model has
+  verified tool calling, only those are offered, so a model the agent cannot
+  drive never becomes the default. Route RPM is reported as not published,
+  because the catalogue does not publish it.
+- Tool calls appear as cards that move from running to succeeded, refused or
+  failed. Changes are shown as a diff and approved one at a time; there is no
+  "always allow".
+- Two-stage Ctrl+C: the first cancels what is running, and a second during
+  cleanup forces out and says that a charge is still possible.
+
+### Same agent, drawn differently
+
+The session drives the same code `mafdet agent` does, so the tools, approvals
+and cost accounting cannot diverge. `--allow-write` and `--allow-command` mean
+exactly what they mean there, and a session given neither has no write or
+command tool loaded at all.
+
+### Nothing that reads the output is affected
+
+In a pipeline, under `--json` or `--quiet`, in CI, with `TERM=dumb`, or with
+`--no-tui`, `mafdet` behaves exactly as it did in 0.3: usage on stderr, exit 2.
+
+### Known limitations
+
+- macOS and Windows are still unverified. Linux, WSL, tmux, SSH and SSH+tmux
+  were checked on real terminals.
+- ASCII is still the default. The block wordmark appears only where the
+  encoding is known to be UTF-8: a UTF-8 locale, or Windows Terminal.
+
 ## 0.3.0 — 2026-08-07
 
 First published release. It contains everything through the plan's 0.3 scope,

package/README.md

@@ -3,7 +3,7 @@
 The official Mafdet AI command line: model calls, account queries, and a
 permissioned local agent.
 
-> **0.3.0.** 中文版见 [README.zh-CN.md](./README.zh-CN.md). The CLI never
+> **0.4.0.** 中文版见 [README.zh-CN.md](./README.zh-CN.md). The CLI never
 > advertises a command it cannot serve, so `mafdet help` always lists exactly
 > what works.
 >
@@ -25,10 +25,29 @@ Or build it from this repository:
 
 ```bash
 pnpm --filter @mafdet/cli build
-cd packages/cli && npm pack          # -> mafdet-cli-0.3.0.tgz
-npm install -g ./mafdet-cli-0.3.0.tgz
+cd packages/cli && npm pack          # -> mafdet-cli-0.4.0.tgz
+npm install -g ./mafdet-cli-0.4.0.tgz
 ```
 
+## The interactive session
+
+Run `mafdet` with no arguments in a terminal and it opens a session: pick how
+to authenticate, choose a model, then talk to the agent.
+
+```bash
+mafdet                       # read-only
+mafdet --allow-write         # changes are shown as a diff and confirmed first
+mafdet --allow-command "pnpm test"
+```
+
+It is the same agent as `mafdet agent`, drawn differently - the same tools, the
+same approvals, the same cost accounting. The flags mean exactly what they mean
+there, and a session given neither has no write or command tool loaded at all.
+
+`mafdet` in a pipeline, under `--json`, in CI, or with `--no-tui` behaves
+exactly as it did in 0.3: usage on stderr, exit 2. Nothing that reads the
+CLI's output will start receiving a drawing.
+
 ## Quickstart
 
 ```bash

package/README.zh-CN.md

@@ -2,7 +2,7 @@
 
 Mafdet AI 官方命令行：模型调用、账户查询，以及一个受权限约束的本地 Agent。
 
-> **0.3.0。** 英文版见 [README.md](./README.md)。
+> **0.4.0。** 英文版见 [README.md](./README.md)。
 
 ## 环境要求
 
@@ -14,6 +14,22 @@ Node.js 20 或更高，以及一把 Mafdet API Key。
 npm install -g @mafdet/cli
 ```
 
+## 交互式会话
+
+在终端里不带参数直接敲 `mafdet` 就进入会话：选认证方式、选模型，然后和 Agent 对话。
+
+```bash
+mafdet                       # 只读
+mafdet --allow-write         # 改动先展示 diff 再确认
+mafdet --allow-command "pnpm test"
+```
+
+它和 `mafdet agent` 是**同一个 Agent**，只是画法不同——同样的工具、同样的审批、
+同样的计费。参数含义与那边完全一致，两个都不给的会话**根本没有加载**写工具和命令工具。
+
+管道里、`--json` 下、CI 中、或带 `--no-tui` 时，`mafdet` 的行为与 0.3 完全一样：
+用法写 stderr、exit 2。**任何读取 CLI 输出的程序都不会突然收到一个界面。**
+
 ## 快速开始
 
 ```bash

package/dist/agent/loop.d.ts

@@ -56,9 +56,26 @@ export interface AgentOptions {
     now?: () => number;
     random?: () => number;
 }
+/**
+ * Progress, for whoever is drawing.
+ *
+ * The lifecycle events (`tool_started`, `tool_awaiting_approval`) were added
+ * for the TUI's tool cards in CLI-021. They are additive: `tool` and
+ * `declined` still fire exactly as before, so the line-based session renders
+ * unchanged and the two surfaces cannot drift on what happened - only on how
+ * it is shown.
+ */
 export type AgentEvent = {
     type: "turn";
     turn: number;
+} | {
+    type: "tool_started";
+    name: string;
+    arguments: string;
+} | {
+    type: "tool_awaiting_approval";
+    name: string;
+    summary: string;
 } | {
     type: "tool";
     name: string;

package/dist/agent/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/agent/loop.ts"],"names":[],"mappings":"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"}

package/dist/agent/loop.js

@@ -101,6 +101,11 @@ export async function runAgent(options) {
         for (const call of calls) {
             if (options.signal?.aborted)
                 return stop(report, "cancelled");
+            options.onEvent?.({
+                type: "tool_started",
+                name: call.function.name,
+                arguments: call.function.arguments,
+            });
             const { text, ok } = await runToolCall(call, byName, options);
             report.toolRuns.push({ name: call.function.name, ok });
             options.onEvent?.({
@@ -160,13 +165,18 @@ async function runToolCall(call, byName, options) {
         // An action can carry advance approval - an --allow-command entry the user
         // declared up front - which is the only way anything runs unprompted.
         const approver = options.approver;
-        const approved = action.preApproved === true ||
-            (approver
-                ? await approver.approve({
-                    summary: action.summary,
-                    preview: action.preview,
-                })
-                : false);
+        let approved = action.preApproved === true;
+        if (!approved && approver) {
+            options.onEvent?.({
+                type: "tool_awaiting_approval",
+                name: tool.name,
+                summary: action.summary,
+            });
+            approved = await approver.approve({
+                summary: action.summary,
+                preview: action.preview,
+            });
+        }
         if (!approved) {
             options.onEvent?.({
                 type: "declined",

package/dist/agent/session.d.ts

@@ -1,7 +1,7 @@
 import type { HttpClient } from "../api/http.js";
 import type { CatalogModel } from "../api/models.js";
 import type { Approver } from "./approvals.js";
-import { type ChatMessage } from "./loop.js";
+import { type AgentEvent, type ChatMessage } from "./loop.js";
 import type { ToolContext, ToolDefinition } from "./tools/types.js";
 export interface SessionOptions {
     client: HttpClient;
@@ -25,6 +25,13 @@ export interface SessionOptions {
      */
     readLine?: () => Promise<string | undefined>;
     signal?: AbortSignal;
+    /**
+     * Where progress goes. Defaults to the line-based rendering below; the TUI
+     * (CLI-021) supplies its own so that both surfaces share this session's
+     * conversation, cost accounting and approval flow, and differ only in how
+     * the same events are drawn.
+     */
+    onEvent?: (event: AgentEvent) => void;
 }
 export interface SessionSummary {
     goals: number;

package/dist/agent/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAapE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,oEAAoE;IACpE,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CAwFzB;AAgHD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CA2B7D"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAY,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAapE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,oEAAoE;IACpE,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CAwFzB;AAgHD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CA2B7D"}

package/dist/agent/session.js

@@ -80,7 +80,7 @@ export async function runSession(options) {
                 history,
                 approver: options.approver,
                 signal: options.signal,
-                onEvent: (event) => reportEvent(event, options),
+                onEvent: options.onEvent ?? ((event) => reportEvent(event, options)),
             });
             summary.turns += report.turns;
             summary.modelRequests += report.modelRequests;

package/dist/commands/agent.d.ts

@@ -1,5 +1,8 @@
+import { type ApprovalMode } from "../agent/approvals.js";
 import { ExitCode } from "../output/exit-codes.js";
 import { type CommandIo } from "./runtime.js";
+export declare const READ_ONLY_PROMPT = "You are the Mafdet CLI agent working inside a user's workspace.\n\nUse the provided tools to inspect the workspace. You cannot modify anything:\nthere are no write or shell tools, so do not claim to have changed a file.\nRead before you conclude - never guess a file's contents. When you have the\nanswer, reply with it directly instead of calling another tool. Be concise.";
+export declare const WRITE_PROMPT = "You are the Mafdet CLI agent working inside a user's workspace.\n\nInspect with the read tools, and change files with edit_file and create_file.\nAlways read a file before editing it, and quote old_text exactly as it appears,\nwith enough surrounding lines to be unique - a near miss is refused rather than\nguessed at. Every change is shown to the user and applied only if they accept\nit; if one is declined, do not retry the same change. There is no shell, so do\nnot claim to have run anything. Be concise.";
 export interface AgentIo extends CommandIo {
     signal?: AbortSignal;
     /** Overridden in tests; production reads the TTY. */
@@ -7,4 +10,10 @@ export interface AgentIo extends CommandIo {
     approver?: import("../agent/approvals.js").Approver;
 }
 export declare function agentCommand(argv: readonly string[], io: AgentIo): Promise<ExitCode>;
+/**
+ * A tool the run cannot use is not offered at all. Read-only means the model
+ * never sees a write tool, and run_command appears only when the user named at
+ * least one allowed command or can approve interactively.
+ */
+export declare function buildToolset(mode: ApprovalMode, hasAllowedCommands: boolean): import("../agent/tools/types.js").ToolDefinition<import("zod").ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>>[];
 //# sourceMappingURL=agent.d.ts.map

package/dist/commands/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/commands/agent.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGnD,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AA6BtB,MAAM,WAAW,OAAQ,SAAQ,SAAS;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qDAAqD;IACrD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,uBAAuB,EAAE,QAAQ,CAAC;CACrD;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,OAAO,GACV,OAAO,CAAC,QAAQ,CAAC,CA+GnB"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../src/commands/agent.ts"],"names":[],"mappings":"AAKA,OAAO,EAAe,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAOvE,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGnD,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,cAAc,CAAC;AAatB,eAAO,MAAM,gBAAgB,0XAK+C,CAAC;AAE7E,eAAO,MAAM,YAAY,mgBAOmB,CAAC;AAE7C,MAAM,WAAW,OAAQ,SAAQ,SAAS;IACxC,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,qDAAqD;IACrD,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,EAAE,OAAO,uBAAuB,EAAE,QAAQ,CAAC;CACrD;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,EAAE,EAAE,OAAO,GACV,OAAO,CAAC,QAAQ,CAAC,CA+GnB;AAgFD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,kBAAkB,EAAE,OAAO,0JAI3E"}

package/dist/commands/agent.js

@@ -20,13 +20,13 @@ and every change is shown as a diff and confirmed before it is written. There
 is no flag that approves everything in advance, and a non-interactive run
 cannot write at all.
 `;
-const READ_ONLY_PROMPT = `You are the Mafdet CLI agent working inside a user's workspace.
+export const READ_ONLY_PROMPT = `You are the Mafdet CLI agent working inside a user's workspace.
 
 Use the provided tools to inspect the workspace. You cannot modify anything:
 there are no write or shell tools, so do not claim to have changed a file.
 Read before you conclude - never guess a file's contents. When you have the
 answer, reply with it directly instead of calling another tool. Be concise.`;
-const WRITE_PROMPT = `You are the Mafdet CLI agent working inside a user's workspace.
+export const WRITE_PROMPT = `You are the Mafdet CLI agent working inside a user's workspace.
 
 Inspect with the read tools, and change files with edit_file and create_file.
 Always read a file before editing it, and quote old_text exactly as it appears,
@@ -205,7 +205,7 @@ function parseArgs(argv, io) {
  * never sees a write tool, and run_command appears only when the user named at
  * least one allowed command or can approve interactively.
  */
-function buildToolset(mode, hasAllowedCommands) {
+export function buildToolset(mode, hasAllowedCommands) {
     if (mode === "read-only" && !hasAllowedCommands)
         return READ_ONLY_TOOLS;
     if (mode === "read-only")

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAcA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AA+ClD,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CA4DpE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAcA,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAgDlD,wBAAsB,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,QAAQ,CAAC,CAsGpE"}

package/dist/index.js

@@ -11,6 +11,7 @@ import { embedCommand } from "./commands/embed.js";
 import { speechCommand } from "./commands/speech.js";
 import { modelsCommand } from "./commands/models.js";
 import { ExitCode } from "./output/exit-codes.js";
+import { decideEntry, explainRefusal } from "./tui/route.js";
 // Read from the installed package rather than baking a literal in at build
 // time, so `mafdet --version` can never disagree with what npm installed.
 function version() {
@@ -54,12 +55,8 @@ async function readStdin() {
 }
 export async function run(argv) {
     const [command] = argv;
-    if (command === undefined) {
-        // Not an error the user asked for, but not a result either: usage goes to
-        // stderr so a bare `mafdet` in a pipeline never pollutes stdout.
-        process.stderr.write(HELP);
-        return ExitCode.Usage;
-    }
+    // Asking for help or the version is always answered the same way, terminal
+    // or not. These come first so that neither can be swallowed by the TUI.
     if (command === "help" || command === "--help" || command === "-h") {
         process.stdout.write(HELP);
         return ExitCode.Ok;
@@ -68,6 +65,48 @@ export async function run(argv) {
         process.stdout.write(`${version()}\n`);
         return ExitCode.Ok;
     }
+    // CLI-018: a bare `mafdet` (or one carrying only flags) opens the TUI on an
+    // interactive terminal, and keeps its 0.3 behaviour everywhere else.
+    // `mafdet <command>` never reaches this branch, so the command surface and
+    // its exit codes are untouched.
+    if (command === undefined || command.startsWith("-")) {
+        const decision = decideEntry({
+            argv,
+            stdinIsTTY: process.stdin.isTTY === true,
+            stdoutIsTTY: process.stdout.isTTY === true,
+            env: process.env,
+        });
+        if (decision.kind === "tui") {
+            // Imported here, not at the top: the command path must not pay for
+            // loading the TUI, and `mafdet version` staying fast is the check.
+            const { runTui } = await import("./tui/app.js");
+            return runTui({
+                version: version(),
+                workspace: process.cwd(),
+                stdout: process.stdout,
+                stderr: process.stderr,
+                stdin: process.stdin,
+                env: process.env,
+                host: process,
+                columns: process.stdout.columns,
+                argv,
+                commandIo: {
+                    stdout: (text) => process.stdout.write(text),
+                    stderr: (text) => process.stderr.write(text),
+                    env: process.env,
+                    cwd: process.cwd(),
+                    version: version(),
+                },
+            });
+        }
+        // Not an error the user asked for, but not a result either: usage goes to
+        // stderr so a bare `mafdet` in a pipeline never pollutes stdout.
+        process.stderr.write(HELP);
+        if (decision.kind === "usage") {
+            process.stderr.write(`\nmafdet: ${explainRefusal(decision.refusedBecause)}.\n`);
+        }
+        return ExitCode.Usage;
+    }
     const io = {
         stdout: (text) => process.stdout.write(text),
         stderr: (text) => process.stderr.write(text),

package/dist/tui/adapters/auth.d.ts

@@ -0,0 +1,26 @@
+import { type CommandIo } from "../../commands/runtime.js";
+export interface KeyDiagnosis {
+    readonly ok: boolean;
+    /** Never the key itself. `sk-mafdet-live-<redacted>`, as everywhere else. */
+    readonly fingerprint: string;
+    readonly modelCount: number;
+    /** Undefined when account:read was not granted - not an error. */
+    readonly balance?: string;
+    /** Present when account:read is missing, so the UI can say so once. */
+    readonly missingAccountRead: boolean;
+    /** Set when the key does not work at all. Already redacted. */
+    readonly problem?: string;
+}
+export interface DiagnoseOptions {
+    readonly apiKey: string;
+    readonly io: CommandIo;
+}
+/**
+ * Verify a key with the cheapest calls that prove it works.
+ *
+ * Deliberately never a model completion: asking a model to prove a key is
+ * valid spends the user's money to learn something a catalogue read already
+ * tells us.
+ */
+export declare function diagnoseKey(options: DiagnoseOptions): Promise<KeyDiagnosis>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/tui/adapters/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../src/tui/adapters/auth.ts"],"names":[],"mappings":"AAUA,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAIzE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,YAAY,CAAC,CA4CvB"}

package/dist/tui/adapters/auth.js

@@ -0,0 +1,76 @@
+// CLI-019 · Checking a key, using the machinery that already exists.
+//
+// The TUI owns no API client and no idea of what a valid key is. It calls the
+// same two planes `doctor` does, and it reaches them by building a runtime
+// over an env object it constructs - never by writing to process.env, so a
+// session-only key cannot leak into a child process or a later read.
+import { ApiError } from "../../api/errors.js";
+import { fetchAccessibleModels } from "../../api/models.js";
+import { fetchWallet } from "../../api/account.js";
+import { buildRuntime } from "../../commands/runtime.js";
+import { formatUsd } from "../../output/money.js";
+import { keyFingerprint } from "../../security/redact.js";
+/**
+ * Verify a key with the cheapest calls that prove it works.
+ *
+ * Deliberately never a model completion: asking a model to prove a key is
+ * valid spends the user's money to learn something a catalogue read already
+ * tells us.
+ */
+export async function diagnoseKey(options) {
+    const fingerprint = keyFingerprint(options.apiKey);
+    // A constructed env, not process.env: the key stays inside this call.
+    const runtime = buildRuntime({
+        ...options.io,
+        env: { ...options.io.env, MAFDET_API_KEY: options.apiKey },
+    });
+    let modelCount = 0;
+    try {
+        const models = await fetchAccessibleModels(runtime.dataPlane);
+        modelCount = models.length;
+    }
+    catch (error) {
+        return {
+            ok: false,
+            fingerprint,
+            modelCount: 0,
+            missingAccountRead: false,
+            problem: describeAuthFailure(error),
+        };
+    }
+    // account:read is optional. Without it model calls still work, so its
+    // absence downgrades the display and nothing else.
+    try {
+        const wallet = await fetchWallet(runtime.accountPlane);
+        return {
+            ok: true,
+            fingerprint,
+            modelCount,
+            balance: formatUsd(wallet.available_micro_usd),
+            missingAccountRead: false,
+        };
+    }
+    catch (error) {
+        const scopeProblem = error instanceof ApiError && error.kind === "auth";
+        return {
+            ok: true,
+            fingerprint,
+            modelCount,
+            missingAccountRead: scopeProblem,
+            problem: scopeProblem ? undefined : describeAuthFailure(error),
+        };
+    }
+}
+/**
+ * A sentence for the welcome page. ApiError redacts on construction, so this
+ * cannot reintroduce a key that the error was carrying.
+ */
+function describeAuthFailure(error) {
+    if (error instanceof ApiError) {
+        if (error.kind === "auth") {
+            return "the key was rejected - check it was copied whole, and that it is not revoked";
+        }
+        return error.message;
+    }
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/tui/adapters/models.d.ts

@@ -0,0 +1,47 @@
+import { type ModelSets, type ResolvedModel } from "../../api/models.js";
+import { type CommandIo } from "../../commands/runtime.js";
+/**
+ * The catalogue does not publish a per-route RPM - checked against the live
+ * `/models` response, which has 31 models and no rate field at all. Plan §19.5
+ * says to show `unknown` rather than guess from the model id, so this constant
+ * exists to make the absence explicit instead of quietly dropping the column.
+ */
+export declare const ROUTE_RPM_AVAILABLE = false;
+export interface ModelCatalogue extends ModelSets {
+    /** Callable, described, chat-surface models: what the picker lists. */
+    readonly chat: readonly ResolvedModel[];
+    /** Of those, the ones the agent is allowed to drive. */
+    readonly agentReady: readonly ResolvedModel[];
+}
+export declare function loadCatalogue(options: {
+    readonly apiKey: string;
+    readonly io: CommandIo;
+}): Promise<ModelCatalogue>;
+/** One line of facts under a model's name. Only what the catalogue states. */
+export declare function describeModel(model: ResolvedModel): string;
+/**
+ * Filter by a typed query. Matches the id, the display name, the provider and
+ * the capabilities, so "tool", "deepseek" and "flash" all narrow the list the
+ * way a user would expect.
+ */
+export declare function filterModels(models: readonly ResolvedModel[], query: string): readonly ResolvedModel[];
+export interface SaveResult {
+    readonly saved: boolean;
+    /** Shown to the user: they should know where a preference landed. */
+    readonly path: string;
+    readonly problem?: string;
+}
+/**
+ * Remember a default model in the user config.
+ *
+ * Only `model` is written, and the existing file is re-validated on the way
+ * through, so this can never introduce a credential or an endpoint into a file
+ * that is not allowed to carry one. The write is atomic: a crash must not
+ * leave a half-written config that the next run refuses to parse.
+ */
+export declare function saveDefaultModel(options: {
+    readonly modelId: string;
+    readonly env: NodeJS.ProcessEnv;
+    readonly configPath?: string;
+}): SaveResult;
+//# sourceMappingURL=models.d.ts.map

package/dist/tui/adapters/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../../../src/tui/adapters/models.ts"],"names":[],"mappings":"AAiBA,OAAO,EAIL,KAAK,SAAS,EACd,KAAK,aAAa,EACnB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAKzE;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAQ,CAAC;AAEzC,MAAM,WAAW,cAAe,SAAQ,SAAS;IAC/C,uEAAuE;IACvE,QAAQ,CAAC,IAAI,EAAE,SAAS,aAAa,EAAE,CAAC;IACxC,wDAAwD;IACxD,QAAQ,CAAC,UAAU,EAAE,SAAS,aAAa,EAAE,CAAC;CAC/C;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE;IAC3C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC;CACxB,GAAG,OAAO,CAAC,cAAc,CAAC,CAoB1B;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAkB1D;AASD;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,SAAS,aAAa,EAAE,EAChC,KAAK,EAAE,MAAM,GACZ,SAAS,aAAa,EAAE,CAgB1B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE;IACxC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B,GAAG,UAAU,CA8Cb"}