agent-from-zero 0.35.1 → 0.35.3

package/README.md

@@ -1 +1,142 @@
 # mini-agent
+
+一个照着 Claude Code 做出来的命令行 coding agent，TypeScript 实现，默认接 DeepSeek（任何支持 function calling 的 OpenAI 兼容模型都能换上）。
+
+## 这是什么
+
+mini-agent 是我模仿 Claude Code 自己搓的。从终端 UI 的样子，到背后的各种机制，基本都是照着 Claude Code 的做法来实现的：
+
+- **交互界面**：Ink 终端 UI、方向键审批菜单、多问题表单、`@file` 引用、diff 预览、推理过程流式展示
+- **Skill**：`SKILL.md` 按需加载，项目级放 `.mini-agent/skills/`，全局放 `~/.config/mini-agent/skills/`。和 Claude Code 一样，skill 列表通过带 `<system-reminder>` 的 user message 告诉模型，新增或修改 skill 不用重启；可以用 `/skill <名字> [参数]` 或 `/<名字> [参数]` 手动运行
+- **MCP**：stdio 和 HTTP 两种传输都支持，远程服务器走 OAuth
+- **权限**：allow / ask / deny 三档，deny 永远优先；另外有 plan 模式、auto 模式（交给模型审核）、`--dangerously-skip-permissions`
+- **其他**：上下文压缩、长期记忆、hooks、子 agent、后台任务、todo、撤销、会话续接、成本统计、非交互的 `-p` 模式
+
+这个版本是我自己一直在 dogfooding、边用边改出来的，到现在已经挺顺手了。我把自己工作用的 **Slack** 和 **Linear** MCP 都接了进来，底层模型用的是 DeepSeek。平时主要让它干这些活：
+
+- 查 bug、看日志、定位问题
+- 回 Slack 消息
+- 跑数据 backfill 之类的脏活
+
+## 用下来的感受
+
+老实说，跟 Claude Code 比体验还是差一截。但跟我直接用 DeepSeek 自带的 harness 相比，mini-agent 好用太多了。
+
+说句题外话：我对 A 社这家公司的人品不太认可，但产品确实做得好。至少从 Claude Code 的体验来看，我觉得它远远好过 Codex 和 DeepSeek 的 harness。所以与其从头去想一个 agent 该长什么样，不如直接照着最好的那个来做。
+
+## 安装与配置
+
+### 安装
+
+需要 Node >= 20.6。不用 clone 仓库，直接用 npx 运行 npm 包（包名是 `agent-from-zero`）：
+
+```bash
+npx agent-from-zero
+```
+
+### 配置 API key
+
+推荐把 API key 写进 **shell 的启动配置文件**（zsh 是 `~/.zshrc`，bash 是 `~/.bashrc`），这样在任何目录启动 mini-agent 都能用。默认用 DeepSeek，只需要一个 key（在 [platform.deepseek.com](https://platform.deepseek.com) 获取），变量名是 `DEEPSEEK_API_KEY`：
+
+```bash
+# ~/.zshrc 或 ~/.bashrc
+export DEEPSEEK_API_KEY=sk-你的key
+```
+
+改完运行 `source ~/.zshrc`（或 `source ~/.bashrc`），或者新开一个终端。
+
+如果某个项目想单独用一个 key，也可以在那个目录下放一个 `.env` 文件，写 `DEEPSEEK_API_KEY=sk-...`，不带 `export`。mini-agent 启动时会读当前目录的 `.env`，但**环境变量优先**：shell 配置文件里已经导出的变量，`.env` 里的同名值会被忽略。
+
+### 配置审核模型 judge.model
+
+开启 auto 模式（会话里输入 `/auto`，或启动时加 `--auto`）后，每个需要审批的工具调用会先交给一个审核模型判断：安全的直接执行，有风险或拿不准的仍然问你。审核模型只有两种选择：
+
+1. **主 agent 用的模型**（默认）：和主 agent 共用同一个 API key 和 base URL。没配 `judge.model` 就直接用主 agent 当前的模型。
+2. **Jev**：配好 Jev 的 key 后自动优先用它（见下一节）。
+
+`judge.model` 写在 `~/.config/mini-agent/settings.json`（全局）或 `.mini-agent/settings.json`（项目级）：
+
+```json
+{
+  "judge": { "model": "deepseek-flash" }
+}
+```
+
+注意：`judge.model` 走的是主 agent 的 API 端点，所以只能填主 agent 那个服务商下的模型，不能填别家的模型，也不能在这里填 Jev。不确定的话就不要配，默认用主 agent 的模型最稳妥。
+
+### 配置 Jev（可选）
+
+**Jev 不是必须的**，不配也能正常使用 auto 模式，审核会用上面说的主 agent 模型。
+
+Jev 是 TypeSafe 提供的审核模型。想用的话，和 DeepSeek 的 key 放在同一个地方，加上 Jev 的 key（两个变量名都可以，二选一）：
+
+```bash
+# ~/.zshrc 或 ~/.bashrc
+export JEV_API_KEY=你的key
+# 或者
+export TYPESAFE_API_KEY=你的key
+```
+
+配了 key 之后，下次启动会自动优先用 Jev 审核；Jev 额度用完或出错时，会自动退回主 agent 的模型。Jev 的模型版本默认是 `jev-1.13.0`，要换的话在 settings.json 里设置 `autoMode.model`：
+
+```json
+{
+  "autoMode": { "model": "jev-1.13.0" }
+}
+```
+
+### 换别的模型
+
+和 API key 放在同一个地方，设置这三个变量就行，各家的 base URL 写在 [.env.example](.env.example) 里：
+
+```bash
+export MINI_AGENT_API_KEY=sk-...
+export MINI_AGENT_BASE_URL=https://api.openai.com/v1
+export MINI_AGENT_MODEL=gpt-4.1-mini
+```
+
+模型必须支持 function calling。如果它的上下文窗口比 DeepSeek 小（默认按约 1M 算），在 settings.json 里按模型配置窗口大小，`/model` 切换模型时会跟着变：
+
+```json
+{
+  "contextWindows": { "gpt-4.1-mini": 1000000, "deepseek-v4-pro": 1000000 }
+}
+```
+
+也可以用环境变量 `MINI_AGENT_CONTEXT_WINDOW` 统一覆盖所有模型。
+
+### 上下文和自动压缩
+
+上下文大小用的是 API 每次返回的真实 `prompt_tokens`，再加上之后新增消息的估算值，所以基本是准的。快满时自动压缩：触发点是窗口减去给回复预留的 20k 和 13k 安全余量（约 1M 的窗口大概在 97% 左右）。状态栏的 `ctx N%` 表示离自动压缩还有多远，到 100% 时下一次调用模型前就会先压缩。也可以随时手动 `/compact`。
+
+### 配置 MCP
+
+在 `~/.config/mini-agent/settings.json`（全局）或 `.mini-agent/settings.json`（项目级）的 `mcpServers` 里添加服务器，写法和 Claude Code 一样。保存后会话里自动生效，不用重启：新加的服务器会连上，删掉的会断开，改过的会重连。也可以手动运行 `/mcp reload`。服务器自己的工具有增减时（MCP 的 `tools/list_changed` 通知），工具列表也会自动更新。启动时 MCP 在后台并行连接，不会卡住输入框，哪个连上了它的工具就马上可用；有连接失败的，状态栏右下角会用红色标出是哪个（需要登录的是黄色）。
+
+输入 `/mcp` 选一个服务器，会看到和 Claude Code 一样的详情（状态、登录、协议版本、URL、配置文件位置、能力、工具数）和操作：View tools、Re-authenticate、Clear authentication、Reconnect、Disable。也可以直接敲 `/mcp tools|auth|clear-auth|reconnect|disable|enable <名字>`。
+
+### 非交互模式
+
+```bash
+npx agent-from-zero -p "总结当前改动"
+cat error.log | npx agent-from-zero -p "分析这份日志"
+npx agent-from-zero -p "总结当前改动" --output-format json
+```
+
+## 常用命令
+
+在会话里输入 `/help` 可以看到全部命令，比较常用的有：`/model` `/effort` `/plan` `/auto` `/skills` `/mcp` `/memory` `/compact` `/diff` `/undo` `/resume` `/status` `/cost`。
+
+## 开发
+
+```bash
+git clone https://github.com/ftfw0621/mini-agent.git && cd mini-agent
+npm install
+cp .env.example .env   # 填入 DEEPSEEK_API_KEY
+npm start           # 从源码运行
+npm run typecheck   # 类型检查
+npm test            # 单元测试
+npm run eval        # 回归评测
+```
+
+各个功能的实现思路见 [docs/](docs/)。

package/dist/agent.js

@@ -8,12 +8,12 @@ import { CONFIG, requireApiKey, saveGlobalSetting, PROJECT_SETTINGS_PATH, GLOBAL
 import { runLoop, TerminateReason, MAX_RETRIES, killAllSubAgents } from "./loop.js"; // the state machine
 import { buildSystemMessage, readProjectInstructions } from "./prompt.js"; // the constitution + optional AGENT.md project memory
 import { forgetFilesExcept, registerExternalTool } from "./tools.js"; // file-state reset + tool registration
-import { compactHistory, estimateHistoryTokens, COMPACT_AT } from "./context.js"; // for the manual /compact command
+import { compactHistory, compactThreshold, contextPercent, contextWindowFor } from "./context.js"; // /compact, /model info, the ctx % in the status line
 import { newSessionId, saveSession, latestSession, listSessions, loadSession, setSessionTitle } from "./session.js"; // conversation persistence (project-local) + the /resume picker
 import { generateSessionTitle, setTerminalTitle } from "./title.js"; // concise session name, generated after the first message + the terminal tab that shows it
 import { initTelemetry, emit, statsReport } from "./telemetry.js"; // local-only event log + /stats
 import { runHooks } from "./hooks.js"; // SessionStart lifecycle hook
-import { connectMcpServers, listMcpServers, mcpActionsFor, runMcpAction } from "./mcp.js"; // external tool servers (MCP) + /mcp
+import { connectMcpServers, listMcpServers, MCP_SUBCOMMANDS, mcpActionsFor, mcpServerDetails, reloadMcpServers, runMcpAction, watchMcpConfig } from "./mcp.js"; // external tool servers (MCP) + /mcp
 import { Judge } from "./judge.js"; // optional LLM permission classifier
 import { AutoMode } from "./auto.js";
 import { effortMenu, setEffort, selectedEffort } from "./effort.js";
@@ -33,7 +33,7 @@ import { promptSelect, promptForm } from "./menu.js"; // arrow-key approval menu
 import { editLine } from "./editor.js"; // our own line editor (keeps the status footer pinned even when input wraps)
 import { normalizeDroppedPaths } from "./drop.js"; // drag-and-drop: a dropped file's path → a clean absolute path in the input
 import { rememberTool, readMemory, readMemoryTyped, extractMemories, MEMORY_PATH } from "./memory.js"; // long-term project memory + auto-extract
-import { loadSkills, buildSkillTool, findSkill, skillInstructions } from "./skills.js"; // Markdown-as-plugin skills
+import { allSkills, currentSkills, findSkill, recordSkillUsage, skillLocked, skillMode, userSkillMessages } from "./skills.js"; // Markdown-as-plugin skills
 import { initCostMeter, DEFAULT_PRICING } from "./cost.js"; // token & cost accounting for /cost
 import { launchInk } from "./ink/launch.js"; // the Ink REPL — the default front-end for interactive sessions
 import { listBackground, hasRunningBackground, killAllBackground } from "./background.js"; // background tasks: /bg view + kill-on-exit (Day 37)
@@ -96,7 +96,8 @@ const SESSION_HELP = `commands:
   /memory    show the durable facts the agent remembers about this project
   /status    session usage and vendor account balance/cost
   /cost      tokens, cache hit rate and estimated spend this session (local)
-  /mcp       list configured MCP servers + status; select one to authenticate / reconnect / disable
+  /mcp       list configured MCP servers + status; select one to view tools / authenticate / clear auth / reconnect / disable
+  /mcp reload  re-read mcpServers from settings.json (saves are also picked up automatically)
   /plan      toggle plan mode — research-only; the agent presents a plan you approve before any change
   /effort [level]  list/select the current model’s supported reasoning effort
   /auto      toggle auto mode — risky or uncertain actions still require approval
@@ -109,8 +110,8 @@ const SESSION_HELP = `commands:
   /undo      revert the most recent file write (write_file / edit_file) this session
   /diff      show every file changed this session, as a diff from where it started
   /resume    list recent sessions in this project and continue one of them
-  /skills    list the reusable skills available in this project
-  /skill <name>  run a skill yourself (works even for user-only skills)
+  /skills    manage skills: turn each on, off, or user-only (search with /, sort with t)
+  /skill <name> [args]  run a skill yourself (works even for user-only skills); /<name> [args] works too
   exit       leave (Ctrl+C at the prompt does the same)
 
 keys (at the prompt):
@@ -197,6 +198,8 @@ async function main() {
             disconnectMcp();
         };
     process.on("exit", disconnectMcp); // best-effort cleanup of server subprocesses
+    if (!cli.print)
+        process.on("exit", watchMcpConfig()); // hot reload: a settings.json save adds/removes/reconnects servers, no restart (a one-shot -p run doesn't need it)
     process.on("exit", killAllBackground); // Day 37: SIGKILL any background job (dev server, slow install) so it never outlives the agent as an orphan
     process.on("exit", killAllSubAgents); // mark any still-running sub-agents as killed so they don't leave pending promises
     process.on("exit", stopCronScheduler); // Day s14: stop the setInterval on exit
@@ -219,14 +222,12 @@ async function main() {
     const memCount = readMemory().length;
     if (memCount)
         console.log(chalk.dim(`(long-term memory: ${memCount} facts loaded)`));
-    // Skills: reusable Markdown procedures. The model-invocable ones are exposed
-    // through a single `skill` tool whose description lists them (progressive
-    // disclosure); user-only skills are reachable via /skill <name>.
-    const skills = loadSkills();
-    if (skills.some((s) => !s.disableModelInvocation))
-        registerExternalTool(buildSkillTool(skills));
-    if (skills.length)
-        console.log(chalk.dim(`(skills: ${skills.length} loaded — ${skills.map((s) => s.name).join(", ")})`));
+    // Skills: reusable Markdown procedures, re-read from disk before every model
+    // call (so a new SKILL.md needs no restart). The loop registers the `skill`
+    // tool and sends the listing as a <system-reminder>; here we just announce them.
+    const startupSkills = currentSkills();
+    if (startupSkills.length)
+        console.log(chalk.dim(`(skills: ${startupSkills.length} loaded — ${startupSkills.map((s) => s.name).join(", ")})`));
     // Token/cost meter for this session. Prices come from settings, falling back
     // to the defaults; the loop records usage into it from every stream.
     const costMeter = initCostMeter({
@@ -476,7 +477,7 @@ async function main() {
         // No name: show the current model and a picker.
         console.log(chalk.dim(`model: ${CONFIG.model}\n` +
             (CONFIG.subAgentModel ? `sub-agent model: ${CONFIG.subAgentModel} (delegated task work)\n` : "") +
-            `endpoint: ${CONFIG.baseURL}\ncontext window: ${CONFIG.contextWindow} tokens (compaction at ~${COMPACT_AT})`));
+            `endpoint: ${CONFIG.baseURL}\ncontext window: ${contextWindowFor()} tokens (auto-compact at ~${compactThreshold()})`));
         if (!process.stdin.isTTY)
             return; // no picker without a TTY — switch with: /model <name>
         const models = await listModels();
@@ -493,12 +494,18 @@ async function main() {
         apply(models[choice]); // picker is session-only too; "/model save <name>" to persist
     };
     // /mcp — list configured MCP servers + status, then manage one (like Claude Code).
-    const mcpStatusText = (status) => status === "connected" ? chalk.green("connected") : status === "needs-auth" ? chalk.yellow("needs auth") : status === "failed" ? chalk.red("failed") : chalk.dim("disabled");
+    const mcpStatusText = (status) => status === "connected" ? chalk.green("connected") : status === "needs-auth" ? chalk.yellow("needs auth") : status === "failed" ? chalk.red("failed") : status === "pending" ? chalk.dim("connecting…") : chalk.dim("disabled");
     const handleMcpCommand = async (arg) => {
         const parts = arg.trim().split(/\s+/).filter(Boolean);
-        if (parts.length >= 2 && ["reconnect", "auth", "authenticate", "enable", "disable"].includes(parts[0])) {
+        // /mcp reload — re-read settings.json now (the file watcher normally does this on save).
+        if (parts[0] === "reload") {
+            const changes = await reloadMcpServers();
+            console.log(chalk.dim(changes.length ? `(mcp: ${changes.join(", ")})` : "(mcp: no changes in settings.json)"));
+            return;
+        }
+        if (parts.length >= 2 && MCP_SUBCOMMANDS[parts[0]]) {
             const name = parts.slice(1).join(" ");
-            const action = parts[0] === "auth" || parts[0] === "authenticate" ? "authenticate" : parts[0];
+            const action = MCP_SUBCOMMANDS[parts[0]];
             try {
                 console.log(chalk.dim(await runMcpAction(name, action, (url) => console.log(chalk.dim(`authenticate in your browser: ${url}`)))));
             }
@@ -524,6 +531,7 @@ async function main() {
             return;
         }
         const server = servers[choice];
+        console.log(`\n${chalk.bold(`${server.name} MCP Server`)}\n\n${mcpServerDetails(server)}\n`); // Claude Code's server screen
         const actions = mcpActionsFor(server);
         const actionChoice = await select(actions.map((a) => a.label));
         if (actionChoice < 0) {
@@ -580,10 +588,13 @@ async function main() {
             await handleModelCommand(line.slice("/model".length).trim());
             return true;
         }
-        // /skill <name> runs a skill on the user's behalf — inject its instructions
-        // as a turn so the model follows them. Works for user-only skills too.
+        // /skill <name> [args] runs a skill on the user's behalf. Like Claude Code it
+        // sends two user messages: a <command-name> marker (the model then knows the
+        // skill is already loaded) and the body. Works for user-only skills too.
         if (line === "/skill" || line.startsWith("/skill ")) {
-            const name = line.slice("/skill".length).trim();
+            const skills = currentSkills(); // live — a SKILL.md added mid-session is found
+            const [name = "", ...rest] = line.slice("/skill".length).trim().split(/\s+/);
+            const args = rest.join(" ");
             if (!name) {
                 console.log(chalk.dim(skills.length ? `usage: /skill <name> — available: ${skills.map((s) => s.name).join(", ")}` : "(no skills in this project — add one at .mini-agent/skills/<name>/SKILL.md)"));
                 return true;
@@ -593,8 +604,10 @@ async function main() {
                 console.log(chalk.yellow(`(no skill named "${name}")`));
                 return true;
             }
-            messages.push({ role: "user", content: `Run the "${s.name}" skill.\n\n${skillInstructions(s)}` });
-            autoMode.recordRequest(`Run the "${s.name}" skill.`);
+            for (const content of userSkillMessages(s, args))
+                messages.push({ role: "user", content });
+            autoMode.recordRequest(`/${s.name}${args ? ` ${args}` : ""}`);
+            recordSkillUsage(s.name); // feeds the "/" typeahead's most-used ranking
             console.log(chalk.dim(`(running skill: ${s.name})`));
             running = true;
             interrupted = false;
@@ -606,20 +619,22 @@ async function main() {
                 console.log(chalk.yellow(`\n⚠️ ${EXIT_NOTES[r.reason]}`));
             return true;
         }
-        // /mcp [reconnect|auth|enable|disable <name>]
+        // /mcp [reload | reconnect|auth|enable|disable <name>]
         if (line === "/mcp" || line.startsWith("/mcp ")) {
             await handleMcpCommand(line.slice("/mcp".length).trim());
             return true;
         }
         switch (line) {
             case "/skills": {
+                const skills = allSkills(); // every skill, with its on / user-only / off state (toggle them in the Ink UI's /skills)
                 if (!skills.length) {
                     console.log(chalk.dim("(no skills — add one at .mini-agent/skills/<name>/SKILL.md or ~/.config/mini-agent/skills/)"));
                     return true;
                 }
                 console.log(chalk.dim(`skills in this project:`));
                 for (const s of skills) {
-                    const who = s.disableModelInvocation ? chalk.yellow("user-only") : chalk.green("model+user");
+                    const mode = skillMode(s);
+                    const who = mode === "on" ? chalk.green("on") : mode === "off" ? chalk.dim("off") : chalk.yellow(skillLocked(s) ? "user-only (locked)" : "user-only");
                     console.log(chalk.dim(`  ${s.name} [${who}${chalk.dim("]")} — ${(s.whenToUse || s.description).slice(0, 70)}`));
                 }
                 return true;
@@ -819,6 +834,8 @@ async function main() {
                 return true;
             }
             default:
+                if (line.startsWith("/") && findSkill(currentSkills(), line.slice(1).split(/\s+/)[0]))
+                    return handleCommand(`/skill ${line.slice(1)}`); // /<skill-name> [args], like Claude Code
                 if (line.startsWith("/")) {
                     console.log(chalk.dim(`unknown command: ${line} — try /help`)); // typo guard
                     return true; // still consumed — don't send typos to the model
@@ -857,7 +874,7 @@ async function main() {
         // input stays clean.
         let footer;
         if (process.stdin.isTTY) {
-            const ctxPct = Math.min(100, Math.round((estimateHistoryTokens(messages) / CONFIG.contextWindow) * 100));
+            const ctxPct = contextPercent(messages); // % of the way to auto-compaction
             console.log(""); // one blank line separates the previous answer from the prompt
             footer = statusLine(CONFIG.model, path.basename(process.cwd()), gitBranch(), ctxPct, costMeter.cost(), Date.now() - sessionStartedAt); // status pinned below the prompt
         }

package/dist/completion.js

@@ -1,8 +1,9 @@
+import Fuse from "fuse.js"; // the fuzzy matcher Claude Code's "/" typeahead uses
 import { effortMenu } from "./effort.js";
 export const COMMANDS = [
     { value: "/model", description: "Switch the model for this session", children: true },
     { value: "/effort", description: "Choose this model's reasoning effort", children: true },
-    { value: "/skills", description: "Browse and run available skills", children: true },
+    { value: "/skills", description: "Turn skills on, off, or user-only" },
     { value: "/skill", description: "Run a skill by name", children: true },
     { value: "/help", description: "Show commands and keyboard shortcuts" },
     { value: "/clear", description: "Start a fresh conversation" },
@@ -23,6 +24,86 @@ export const COMMANDS = [
     { value: "/diff", description: "Show file changes this session" },
     { value: "/resume", description: "Choose a previous session" },
 ];
+// Every "/<command>" token in the text that names a real command or skill, as
+// [start, end) code-unit ranges — the input box paints these. Claude Code's
+// rule (findSlashCommandPositions): a "/" at the start or after whitespace,
+// then a letter and [A-Za-z0-9:_-]*, anywhere in the text; it lights up only
+// if that name exists. So "/grill-me," lights up, "/grill" and "a/grill-me" don't.
+export function commandTokenRanges(text, names) {
+    const known = new Set(names.map((n) => n.toLowerCase()));
+    const out = [];
+    for (const m of text.matchAll(/(^|\s)(\/[a-zA-Z][a-zA-Z0-9:\-_]*)/g)) {
+        const start = (m.index ?? 0) + m[1].length;
+        if (known.has(m[2].slice(1).toLowerCase()))
+            out.push([start, start + m[2].length]);
+    }
+    return out;
+}
+// Names a "/" can reach: built-in commands, then skills (a built-in wins a clash — it is what runs).
+export function commandNames(ctx) {
+    const builtins = COMMANDS.map((c) => c.value.slice(1));
+    return [...builtins, ...ctx.skills.map((s) => s.name).filter((n) => !builtins.includes(n))];
+}
+function typeaheadItems(ctx) {
+    const builtins = new Set(COMMANDS.map((c) => c.value));
+    const skills = ctx.skills
+        .filter((s) => !builtins.has(`/${s.name}`))
+        .map((s) => ({
+        value: `/${s.name}`,
+        name: s.name,
+        // Claude Code's formatDescriptionWithSource: "desc (User)" / "desc (Project)", plus the argument names.
+        description: `${s.description || s.whenToUse}${s.source ? ` (${s.source === "project" ? "Project" : "User"})` : ""}${s.argNames?.length ? ` (arguments: ${s.argNames.join(", ")})` : ""}`,
+        children: Boolean(s.argNames?.length), // takes arguments → Enter fills it in; none → Enter runs it
+        group: s.source ?? "user",
+        usage: ctx.usage?.(s.name) ?? 0,
+    }));
+    return [...COMMANDS.map((c) => ({ ...c, name: c.value.slice(1), group: "builtin", usage: 0 })), ...skills];
+}
+// The "/" typeahead, Claude Code's generateCommandSuggestions:
+//   bare "/"  → your 5 most-used skills, then built-ins, then user skills, then
+//               project skills, each group alphabetical
+//   "/query"  → Fuse.js over name (weight 3), name parts split on :_- (2) and
+//               description words (0.5), threshold 0.3; then re-sorted: exact
+//               name, then name prefix (shorter first), then fuzzy score (when
+//               it differs by > 0.1), then usage
+function commandTypeahead(input, ctx) {
+    const items = typeaheadItems(ctx);
+    const q = input.slice(1).toLowerCase();
+    const alpha = (a, b) => a.name.localeCompare(b.name);
+    if (!q) {
+        const top = items.filter((i) => i.usage > 0).sort((a, b) => b.usage - a.usage).slice(0, 5);
+        const rest = (group) => items.filter((i) => i.group === group && !top.includes(i)).sort(alpha);
+        return [...top, ...rest("builtin"), ...rest("user"), ...rest("project")];
+    }
+    const docs = items.map((item) => {
+        const parts = item.name.split(/[:_-]/);
+        return { item, commandName: item.name.toLowerCase(), partKey: parts.length > 1 ? parts.map((p) => p.toLowerCase()) : undefined, descriptionKey: item.description.toLowerCase().split(/\s+/).map((w) => w.replace(/[^a-z0-9]/g, "")).filter(Boolean) };
+    });
+    const fuse = new Fuse(docs, { includeScore: true, threshold: 0.3, location: 0, distance: 100, keys: [{ name: "commandName", weight: 3 }, { name: "partKey", weight: 2 }, { name: "descriptionKey", weight: 0.5 }] });
+    const rank = (name) => (name === q ? 0 : name.startsWith(q) ? 1 : 2);
+    return fuse.search(q).sort((a, b) => {
+        const an = a.item.commandName, bn = b.item.commandName;
+        if (rank(an) !== rank(bn))
+            return rank(an) - rank(bn);
+        if (rank(an) === 1 && an.length !== bn.length)
+            return an.length - bn.length;
+        const ds = (a.score ?? 0) - (b.score ?? 0);
+        if (Math.abs(ds) > 0.1)
+            return ds;
+        return b.item.item.usage - a.item.item.usage;
+    }).map((r) => r.item.item);
+}
+// A "/" in the middle of the text gets no list — just ghost text: the rest of
+// the best prefix match, dim, after the cursor; Tab accepts it as "/name ".
+// (Claude Code: getBestCommandMatch on /\s\/([a-zA-Z0-9_:-]*)$/ before the cursor.)
+export function inlineCommandGhost(beforeCursor, ctx) {
+    const m = beforeCursor.match(/\s\/([a-zA-Z0-9_:-]+)$/);
+    if (!m)
+        return null;
+    const partial = m[1].toLowerCase();
+    const best = commandNames(ctx).filter((n) => n.toLowerCase().startsWith(partial) && n.length > partial.length).sort((a, b) => a.length - b.length || a.localeCompare(b))[0];
+    return best ? { start: beforeCursor.length - m[1].length - 1, suffix: best.slice(partial.length), full: best } : null;
+}
 export function slashCompletions(input, ctx) {
     if (!input.startsWith("/") || /[\r\n]/.test(input))
         return null;
@@ -33,7 +114,7 @@ export function slashCompletions(input, ctx) {
         const menu = effortMenu(ctx.model);
         return { items: filter(menu.values.map((value, i) => ({ value: `/effort ${value}`, description: menu.labels[i] }))), hint: menu.header };
     }
-    if (command === "/skills" || command === "/skill") {
+    if ((command === "/skills" && parts.length) || command === "/skill") { // bare "/skills" opens the manager; "/skills <name>" still runs one
         return { items: ctx.skills.filter((s) => s.name.toLowerCase().startsWith(arg)).map((s) => ({ value: `/skill ${s.name}`, description: s.whenToUse || s.description })), hint: ctx.skills.length ? "Choose a skill to run" : "No skills found in project or user skill directories" };
     }
     if (command === "/model") {
@@ -58,8 +139,17 @@ export function slashCompletions(input, ctx) {
             ], input.trimEnd()) };
     }
     if (command === "/mcp") {
-        const items = [{ value: "/mcp", description: "Open MCP server menu" }, ...["reconnect", "auth", "enable", "disable"].flatMap((action) => ctx.servers.map((name) => ({ value: `/mcp ${action} ${name}`, description: `${action} ${name}` })))];
+        const items = [{ value: "/mcp", description: "Open MCP server menu" }, { value: "/mcp reload", description: "Re-read MCP servers from settings.json" }, ...["tools", "auth", "clear-auth", "reconnect", "enable", "disable"].flatMap((action) => ctx.servers.map((name) => ({ value: `/mcp ${action} ${name}`, description: `${action} ${name}` })))];
         return { items: filter(items, input.trimEnd()) };
     }
+    if (!/\s/.test(input))
+        return { items: commandTypeahead(input, ctx), hint: "No matching commands or skills" };
+    // "/<skill> args…": the user is typing arguments now — no list, just the
+    // skill's argument hint while it has one (Claude Code's argumentHint).
+    const skill = ctx.skills.find((s) => `/${s.name.toLowerCase()}` === command.toLowerCase());
+    if (skill) {
+        const hint = skill.argumentHint || (skill.argNames?.length ? skill.argNames.map((a) => `<${a}>`).join(" ") : "");
+        return hint && !arg ? { items: [], hint } : null;
+    }
     return { items: filter(COMMANDS), hint: "Commands" };
 }

package/dist/config.js

@@ -40,6 +40,39 @@ function readSettings(p) {
 }
 const globalSettings = readSettings(GLOBAL_SETTINGS_PATH); // the user's defaults
 const projectSettings = readSettings(PROJECT_SETTINGS_PATH); // this project's rules
+// Re-read ONLY the mcpServers map from both layers, mid-session (the MCP hot
+// reload in mcp.ts). Unlike startup, a file that won't parse is NOT fatal here:
+// an editor saving in two steps can leave half-written JSON for a moment, and
+// killing a live session over that would be absurd. Return null instead — the
+// caller keeps the servers it already has and waits for the next save.
+export function readMcpServers() {
+    const layers = [];
+    for (const p of [GLOBAL_SETTINGS_PATH, PROJECT_SETTINGS_PATH]) {
+        if (!fs.existsSync(p)) {
+            layers.push({});
+            continue;
+        }
+        try {
+            layers.push(JSON.parse(fs.readFileSync(p, "utf8")));
+        }
+        catch {
+            return null; // unparseable right now — don't guess, keep what is running
+        }
+    }
+    return { ...(layers[0].mcpServers ?? {}), ...(layers[1].mcpServers ?? {}) }; // same merge as startup: project wins
+}
+// Which settings file defines this MCP server (the /mcp panel's "Config
+// location"). Project entries override global ones, so check the project first.
+export function mcpConfigPath(name) {
+    try {
+        if (JSON.parse(fs.readFileSync(PROJECT_SETTINGS_PATH, "utf8")).mcpServers?.[name])
+            return PROJECT_SETTINGS_PATH;
+    }
+    catch {
+        /* no project settings (or unreadable) — it's global */
+    }
+    return GLOBAL_SETTINGS_PATH;
+}
 // Provider-agnostic configuration. Resolution order, most specific wins:
 //   env MINI_AGENT_*  >  project settings  >  global settings  >  legacy DEEPSEEK_* env  >  defaults
 export const CONFIG = {
@@ -51,12 +84,16 @@ export const CONFIG = {
     apiKey: process.env.MINI_AGENT_API_KEY || // generic key wins...
         process.env.DEEPSEEK_API_KEY || // ...over the back-compat one
         "", // empty = missing; requireApiKey() turns that into a helpful error
-    model: process.env.MINI_AGENT_MODEL || projectSettings.model || globalSettings.model || "deepseek-chat", // must support function calling
+    model: process.env.MINI_AGENT_MODEL || projectSettings.model || globalSettings.model || "deepseek-flash", // must support function calling
     effortProfiles: { ...(globalSettings.effortProfiles ?? {}), ...(projectSettings.effortProfiles ?? {}) },
     // Sub-agents (the task tool) can run on a DIFFERENT model than the orchestrator:
     // a cheap/fast one for grunt work (reading many files, broad search), or a
     // strong one as an "advisor" to double-check. undefined → use the main model.
     subAgentModel: process.env.MINI_AGENT_SUBAGENT_MODEL || projectSettings.subAgentModel || globalSettings.subAgentModel || undefined,
+    // /skills on/off/user-only choices. Project entries override global ones.
+    skillOverrides: { ...(globalSettings.skillOverrides ?? {}), ...(projectSettings.skillOverrides ?? {}) },
+    // Per-model windows (context.ts contextWindowFor): project entries override global ones.
+    contextWindows: { ...(globalSettings.contextWindows ?? {}), ...(projectSettings.contextWindows ?? {}) },
     contextWindow: Number(process.env.MINI_AGENT_CONTEXT_WINDOW) || // env override first
         projectSettings.contextWindow || // then files
         globalSettings.contextWindow ||

package/dist/context.js

@@ -2,14 +2,33 @@ import { effortMessages } from "./effort.js";
 import fs from "node:fs"; // re-reading files from disk during recovery
 import chalk from "chalk"; // status lines
 import { CONFIG } from "./config.js"; // the resolved context window (env > settings files > default)
-import { recentFiles, forgetFilesExcept } from "./tools.js"; // session file state (what was read/edited, and when)
+import { recentFiles, forgetFilesExcept, toolDefinitions } from "./tools.js"; // session file state (what was read/edited, and when) + the tool manuals we send
 // ---- The context window ------------------------------------------------------
 // The default (1,048,565) came from a real API error message, not from docs.
 // Trust what the API tells you over what you remember reading.
-export const CONTEXT_WINDOW = CONFIG.contextWindow; // resolved in config.ts: env > project file > global file > default
-// Compact well before the hard limit: estimation is approximate and the summary
-// itself needs room. 80% is deliberately conservative.
-export const COMPACT_AT = Number(process.env.MINI_AGENT_COMPACT_AT || Math.floor(CONTEXT_WINDOW * 0.8)); // env override kept so tests can trigger compaction cheaply
+//
+// The window belongs to a MODEL, not to the session: /model can switch to one
+// with a smaller window mid-conversation. Resolution, most specific first:
+//   env MINI_AGENT_CONTEXT_WINDOW  >  settings contextWindows[<model>]  >  settings contextWindow  >  default
+export function contextWindowFor(model = CONFIG.model) {
+    return Number(process.env.MINI_AGENT_CONTEXT_WINDOW) || CONFIG.contextWindows[model] || CONFIG.contextWindow;
+}
+// When to compact, the Claude Code way: not at a fixed percentage, but at
+// "window minus what we must keep free". Two reservations:
+//   - room for the model's reply (the compaction call itself writes a summary)
+//   - a safety buffer for what we can't count exactly (the tail estimate)
+// On a ~1M window that's ~97% full; on a 128k window it's ~74%, because the
+// same 33k is a bigger slice of a smaller window. The floor keeps a tiny window
+// from getting a threshold at or below zero.
+export const RESERVED_OUTPUT_TOKENS = 20_000; // Claude Code reserves min(max output, 20k)
+export const AUTOCOMPACT_BUFFER_TOKENS = 13_000; // Claude Code's AUTOCOMPACT_BUFFER_TOKENS
+export function compactThreshold(model = CONFIG.model) {
+    const env = Number(process.env.MINI_AGENT_COMPACT_AT); // explicit override (tests use it to trigger compaction cheaply)
+    if (env)
+        return env;
+    const window = contextWindowFor(model);
+    return Math.max(Math.floor(window * 0.6), window - RESERVED_OUTPUT_TOKENS - AUTOCOMPACT_BUFFER_TOKENS);
+}
 // How many times one query may compact / fail to compact before we give up.
 export const MAX_COMPACTIONS_PER_QUERY = 4; // a query that needs more is too big — stop, don't loop
 export const MAX_COMPACT_FAILURES = 3; // the compaction circuit breaker
@@ -37,6 +56,27 @@ export function estimateHistoryTokens(messages) {
     }
     return total;
 }
+const usageAnchors = new WeakMap();
+export function recordContextUsage(messages, sentCount, usage) {
+    const promptTokens = Number(usage?.prompt_tokens ?? 0);
+    if (!sentCount || !promptTokens)
+        return; // nothing sent, or a provider that doesn't report input tokens
+    usageAnchors.set(messages, { last: messages[sentCount - 1], count: sentCount, promptTokens });
+}
+// The tool manuals ride along on every request but aren't messages — a
+// history-only estimate misses them (dozens of MCP tools can be tens of thousands of tokens).
+export const estimateToolTokens = () => estimateTokens(JSON.stringify(toolDefinitions()), true);
+export function contextTokens(messages) {
+    const a = usageAnchors.get(messages);
+    if (a && messages.length >= a.count && messages[a.count - 1] === a.last)
+        return a.promptTokens + estimateHistoryTokens(messages.slice(a.count));
+    return estimateHistoryTokens(messages) + estimateToolTokens(); // no (valid) measurement yet — estimate it all
+}
+// For the status bar: how close we are to AUTO-COMPACTION (not to the hard
+// limit). 100% means the next model call compacts first.
+export function contextPercent(messages, model = CONFIG.model) {
+    return Math.min(100, Math.round((contextTokens(messages) / compactThreshold(model)) * 100));
+}
 // ---- The summary prompt ---------------------------------------------------------
 // Six numbered sections. Each exists because losing that piece of information
 // causes a specific, real failure mode after compaction (e.g. losing section 4
@@ -88,7 +128,7 @@ client, // the same client the loop uses
 model, // the same model summarizes its own conversation
 signal, // Ctrl+C must abort compaction too
 log = (s) => console.log(s)) {
-    const before = estimateHistoryTokens(messages); // for the log line
+    const before = contextTokens(messages); // for the log line — measured, not just estimated
     log(chalk.magenta(`📦 compacting context (~${before} tokens)...`)); // automatic behavior must be visible
     const res = await client.chat.completions.create({
         model, // same model — no need for a fancier one to summarize