agent-from-zero 0.33.1 → 0.34.0

package/dist/agent.js

@@ -8,10 +8,11 @@ import { runLoop, TerminateReason, MAX_RETRIES, killAllSubAgents } from "./loop.
 import { buildSystemMessage } 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 { newSessionId, saveSession, latestSession, listSessions, loadSession } from "./session.js"; // conversation persistence (project-local) + the /resume picker
+import { newSessionId, saveSession, latestSession, listSessions, loadSession, setSessionTitle } from "./session.js"; // conversation persistence (project-local) + the /resume picker
+import { generateSessionTitle } from "./title.js"; // concise session name, generated after the first message
 import { initTelemetry, emit, statsReport } from "./telemetry.js"; // local-only event log + /stats
 import { runHooks } from "./hooks.js"; // SessionStart lifecycle hook
-import { connectMcpServers } from "./mcp.js"; // external tool servers (MCP)
+import { connectMcpServers, listMcpServers, mcpActionsFor, runMcpAction } from "./mcp.js"; // external tool servers (MCP) + /mcp
 import { Judge } from "./judge.js"; // optional LLM permission classifier
 import { isPlanMode, setPlanMode } from "./permissions.js"; // plan mode: research-only until the user approves a plan
 import { undoLast, clearUndo, sessionChanges } from "./undo.js"; // /undo + /diff: take back, or review, this session's writes
@@ -71,6 +72,7 @@ const SESSION_HELP = `commands:
   /stats     event counts for this session (local telemetry — nothing leaves this machine)
   /memory    show the durable facts the agent remembers about this project
   /cost      tokens, cache hit rate and estimated spend this session (local)
+  /mcp       list configured MCP servers + status; select one to authenticate / reconnect / disable
   /plan      toggle plan mode — research-only; the agent presents a plan you approve before any change
   /todos     show the agent's current task plan (it maintains one with todo_write on multi-step work)
   /bg        list background tasks this session (run_bash_background) and their status
@@ -201,6 +203,8 @@ async function main() {
     let running = false; // is a task currently executing?
     let interrupted = false; // has the current task been interrupted?
     let controller = new AbortController(); // aborts the in-flight API request
+    let titleAttempted = false; // one-shot: name the session once, after the first real message
+    let pendingTitle; // the generated title, passed into the next save
     // ---- One-shot print mode -------------------------------------------------------
     // The same loop, the same permission gate (fail closed without a TTY), no REPL.
     // Designed for scripts: the exit code distinguishes success from every failure.
@@ -409,6 +413,51 @@ 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 handleMcpCommand = async (arg) => {
+        const parts = arg.trim().split(/\s+/).filter(Boolean);
+        if (parts.length >= 2 && ["reconnect", "auth", "authenticate", "enable", "disable"].includes(parts[0])) {
+            const name = parts.slice(1).join(" ");
+            const action = parts[0] === "auth" || parts[0] === "authenticate" ? "authenticate" : parts[0];
+            try {
+                console.log(chalk.dim(await runMcpAction(name, action, (url) => console.log(chalk.dim(`authenticate in your browser: ${url}`)))));
+            }
+            catch (err) {
+                console.log(chalk.yellow(err.message));
+            }
+            return;
+        }
+        const servers = listMcpServers();
+        if (!servers.length) {
+            console.log(chalk.dim("(no MCP servers configured — add an mcpServers map to .mini-agent/settings.json or ~/.config/mini-agent/settings.json)"));
+            return;
+        }
+        console.log(chalk.dim("MCP servers:"));
+        const labels = servers.map((s) => `${s.name}  ·  ${mcpStatusText(s.status)}${s.tools ? `  ·  ${s.tools} tool${s.tools === 1 ? "" : "s"}` : ""}${s.transport === "http" ? "  ·  http" : "  ·  stdio"}`);
+        for (const label of labels)
+            console.log(chalk.dim(`  ${label}`));
+        if (!process.stdin.isTTY)
+            return;
+        const choice = await promptSelect(rl, labels.map((l) => l.replace(/  ·  /g, " — ")));
+        if (choice < 0) {
+            console.log(chalk.dim("(cancelled)"));
+            return;
+        }
+        const server = servers[choice];
+        const actions = mcpActionsFor(server);
+        const actionChoice = await promptSelect(rl, actions.map((a) => a.label));
+        if (actionChoice < 0) {
+            console.log(chalk.dim("(cancelled)"));
+            return;
+        }
+        try {
+            console.log(chalk.dim(await runMcpAction(server.name, actions[actionChoice].action, (url) => console.log(chalk.dim(`authenticate in your browser: ${url}`)))));
+        }
+        catch (err) {
+            console.log(chalk.yellow(err.message));
+        }
+    };
     // Handle a /slash command. Returns true if the line was a command.
     const handleCommand = async (line) => {
         // /model takes an optional argument (/model <name>), so it can't be a plain
@@ -442,6 +491,11 @@ async function main() {
                 console.log(chalk.yellow(`\n⚠️ ${EXIT_NOTES[r.reason]}`));
             return true;
         }
+        // /mcp [reconnect|auth|enable|disable <name>]
+        if (line === "/mcp" || line.startsWith("/mcp ")) {
+            await handleMcpCommand(line.slice("/mcp".length).trim());
+            return true;
+        }
         switch (line) {
             case "/skills": {
                 if (!skills.length) {
@@ -468,6 +522,8 @@ async function main() {
                 clearReasoning(); // drop the collapsed thinking too
                 clearToolCalls(); // ...and the folded tool-call trace
                 sessionId = newSessionId(); // a fresh conversation is a fresh session file
+                titleAttempted = false; // a fresh session gets its own title on its first message
+                pendingTitle = undefined;
                 console.log(chalk.dim("(history cleared)")); // confirm the reset
                 return true;
             case "/todos": {
@@ -589,6 +645,8 @@ async function main() {
                 }
                 messages = [{ role: "system", content: systemMessage }, ...chosen.messages]; // fresh constitution + saved turns
                 sessionId = chosen.id; // keep appending to the resumed session's file
+                titleAttempted = false; // a resumed session without a title gets one on its next message
+                pendingTitle = chosen.title;
                 forgetFilesExcept([]); // a resumed conversation must re-read files before editing them
                 clearUndo(); // the previous session's writes are not ours to undo
                 clearTodos(); // the resumed task starts without the old session's stale plan
@@ -713,6 +771,22 @@ async function main() {
             console.log(chalk.dim(`(attached ${attached.length} file${attached.length === 1 ? "" : "s"}: ${attached.join(", ")})`));
         if (refused.length)
             console.log(chalk.yellow(`(refused secret file${refused.length === 1 ? "" : "s"}: ${refused.join(", ")})`));
+        // Name the session once, after the first real user message. Same as the Ink
+        // REPL: a cheap model call distills the prompt into a 3-7 word title, fired
+        // and forgotten so it never delays the turn; a failure leaves the raw prompt.
+        if (!titleAttempted) {
+            titleAttempted = true;
+            if (!loadSession(sessionId)?.title) {
+                void generateSessionTitle(client, CONFIG.subAgentModel || CONFIG.model, line)
+                    .then((title) => {
+                    if (title) {
+                        pendingTitle = title;
+                        setSessionTitle(sessionId, title);
+                    }
+                })
+                    .catch(() => { });
+            }
+        }
         messages.push({ role: "user", content: augmented + injected }); // the new turn (with any attached files + hook context) joins the shared history
         clearReasoning(); // Ctrl+R should reveal THIS turn's thinking, not the previous answer's
         clearToolCalls(); // ...and Ctrl+T should reveal THIS turn's tool calls
@@ -730,7 +804,7 @@ async function main() {
             judge, // optional LLM classifier for the "ask" middle ground
         });
         running = false; // back at the prompt — Ctrl+C means "exit" again
-        saveSession(sessionId, CONFIG.model, messages); // snapshot after every turn — crash-safe by construction
+        saveSession(sessionId, CONFIG.model, messages, pendingTitle); // snapshot after every turn — crash-safe by construction
         // Auto-extract memories (opt-in: settings.memory.autoExtract). A cheap pass
         // that saves durable facts — especially user corrections — so memory
         // captures itself instead of relying on the model to call `remember`.

package/dist/ink/app.js

@@ -17,7 +17,8 @@ import { clearReasoning, clearToolCalls, getReasoning, getToolCalls, cleanup as
 import { expandMentions } from "../mentions.js"; // @file mentions → attach file contents
 import { normalizeDroppedPaths } from "../drop.js"; // drag-and-drop a file → its absolute path in the input
 import { cronItemsPending, consumeCronQueue, cronTriggerContent } from "../cron.js"; // cron scheduler (Day s14): fire scheduled jobs autonomously while idle
-import { newSessionId, saveSession, listSessions, loadSession } from "../session.js";
+import { newSessionId, saveSession, listSessions, loadSession, setSessionTitle } from "../session.js";
+import { generateSessionTitle } from "../title.js"; // concise session name, generated after the first message
 import { isPlanMode, setPlanMode } from "../permissions.js";
 import { findSkill, skillInstructions } from "../skills.js";
 import { extractMemories } from "../memory.js";
@@ -25,7 +26,8 @@ import { displayWidth } from "../editor.js"; // display-width measurement (CJK-a
 import { runHooks } from "../hooks.js";
 import { emit } from "../telemetry.js";
 import { makeInkSink } from "./sink.js"; // turns the loop's output into React state
-import { runInfoCommand } from "./commands.js"; // the non-interactive slash commands
+import { runInfoCommand, mcpStatusText } from "./commands.js"; // the non-interactive slash commands + /mcp status
+import { listMcpServers, mcpActionsFor, runMcpAction } from "../mcp.js"; // /mcp: list + per-server actions
 // Injected when plan mode turns on, so the model knows the rules it now lives in.
 const PLAN_MODE_NOTICE = `[plan mode ON] Investigate this request using only read-only tools — read_file, search, and safe read-only shell (ls, cat, git status). Do NOT write files, edit, or run mutating commands; the permission gate will block them. When you have a concrete, ordered plan, call the exit_plan_mode tool with that plan. The user reviews and approves it before you make any change.`;
 const SPINNER_FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]; // the braille spinner ora uses, hand-rolled for Ink
@@ -117,6 +119,8 @@ export function App({ session, runTurn }) {
     const sink = useRef(makeInkSink({ setStatus, setLive, pushItem })).current;
     const history = useRef([]).current; // past prompts, for ↑/↓ recall
     const turn = useRef(null); // the in-flight turn, for Esc-interrupt
+    const titleAttempted = useRef(false); // one-shot: name the session once, after the first real message
+    const pendingTitle = useRef(undefined); // the generated title, passed into the next save
     useEffect(() => {
         const id = setInterval(() => setTick((t) => t + 1), 1000);
         return () => clearInterval(id);
@@ -164,7 +168,7 @@ export function App({ session, runTurn }) {
             .then(async (result) => {
             if (result.reason !== TerminateReason.Done)
                 note(chalk.yellow(`⚠️ ${EXIT_NOTES[result.reason] ?? result.reason}`));
-            saveSession(sessionId, model, messages); // snapshot after every turn — crash-safe by construction
+            saveSession(sessionId, model, messages, pendingTitle.current); // snapshot after every turn — crash-safe by construction
             if (CONFIG.memory.autoExtract && result.reason === TerminateReason.Done) {
                 try {
                     const got = await extractMemories(client, CONFIG.subAgentModel || model, messages);
@@ -225,15 +229,80 @@ export function App({ session, runTurn }) {
             note(chalk.dim(`(attached ${attached.length} file${attached.length === 1 ? "" : "s"}: ${attached.join(", ")})`));
         if (refused.length)
             note(chalk.yellow(`(refused secret file${refused.length === 1 ? "" : "s"}: ${refused.join(", ")})`));
+        // Name the session once, after the first real user message. A cheap model
+        // call distills the prompt into a 3-7 word title (like Claude Code's aiTitle);
+        // it runs fire-and-forget so it never delays the turn, and a failure just
+        // leaves the raw first prompt as the title. Resumed sessions that already
+        // have a title are left alone.
+        if (!titleAttempted.current) {
+            titleAttempted.current = true;
+            if (!loadSession(sessionId)?.title) {
+                void generateSessionTitle(client, CONFIG.subAgentModel || CONFIG.model, text)
+                    .then((title) => {
+                    if (title) {
+                        pendingTitle.current = title;
+                        setSessionTitle(sessionId, title);
+                    }
+                })
+                    .catch(() => { });
+            }
+        }
         runConversationTurn(augmented + injected, { kind: "user", text }); // show the original line; send the augmented content
     };
     // Handle a /slash command. Returns true if the line was a command (handled).
+    // /mcp — list configured servers + status, then pick one to manage it.
+    const handleMcpCommand = async (arg) => {
+        const parts = arg.trim().split(/\s+/).filter(Boolean);
+        // Direct subcommands (scriptable, matching Claude Code): /mcp reconnect|auth|enable|disable <name>
+        if (parts.length >= 2 && ["reconnect", "auth", "authenticate", "enable", "disable"].includes(parts[0])) {
+            const name = parts.slice(1).join(" ");
+            setBusy(true);
+            try {
+                const action = parts[0] === "auth" || parts[0] === "authenticate" ? "authenticate" : parts[0];
+                const msg = await runMcpAction(name, action, (url) => note(chalk.dim(`authenticate in your browser: ${url}`)));
+                note(chalk.dim(msg));
+            }
+            catch (err) {
+                note(chalk.yellow(err.message));
+            }
+            finally {
+                setBusy(false);
+            }
+            return;
+        }
+        const servers = listMcpServers();
+        if (!servers.length) {
+            note(chalk.dim("(no MCP servers configured — add an mcpServers map to .mini-agent/settings.json or ~/.config/mini-agent/settings.json)"));
+            return;
+        }
+        const labels = servers.map((s) => `${s.name}  ·  ${mcpStatusText(s)}${s.tools ? `  ·  ${s.tools} tool${s.tools === 1 ? "" : "s"}` : ""}${s.transport === "http" ? "  ·  http" : "  ·  stdio"}`);
+        openSelect("MCP servers (pick one to manage):", labels, (i) => {
+            if (i < 0)
+                return note(chalk.dim("(cancelled)"));
+            const server = servers[i];
+            const actions = mcpActionsFor(server);
+            openSelect(`${server.name} — ${mcpStatusText(server)}`, actions.map((a) => a.label), (j) => {
+                if (j < 0)
+                    return note(chalk.dim("(cancelled)"));
+                setBusy(true);
+                runMcpAction(server.name, actions[j].action, (url) => note(chalk.dim(`authenticate in your browser: ${url}`)))
+                    .then((msg) => note(chalk.dim(msg)))
+                    .catch((err) => note(chalk.yellow(err.message)))
+                    .finally(() => setBusy(false));
+            });
+        });
+    };
     const handleCommand = async (line) => {
         const info = runInfoCommand(line, { skills, costMeter }); // /help /cost /memory /stats /todos /bg /team /tasks /skills /undo /diff
         if (info !== null) {
             note(info);
             return true;
         }
+        // /mcp [reconnect|auth|enable|disable <name>]
+        if (line === "/mcp" || line.startsWith("/mcp ")) {
+            await handleMcpCommand(line.slice("/mcp".length).trim());
+            return true;
+        }
         // /model [name|save <name>]
         if (line === "/model" || line.startsWith("/model ")) {
             const arg = line.slice("/model".length).trim();
@@ -301,6 +370,8 @@ export function App({ session, runTurn }) {
                 clearReasoning();
                 clearToolCalls();
                 setSessionId(newSessionId());
+                titleAttempted.current = false; // a fresh session gets its own title on its first message
+                pendingTitle.current = undefined;
                 note(chalk.dim("(history cleared)"));
                 return true;
             case "/plan":
@@ -349,6 +420,8 @@ export function App({ session, runTurn }) {
                     messages.length = 0;
                     messages.push({ role: "system", content: systemMessage }, ...chosen.messages);
                     setSessionId(chosen.id);
+                    titleAttempted.current = false; // a resumed session without a title gets one on its next message
+                    pendingTitle.current = chosen.title;
                     forgetFilesExcept([]);
                     clearUndo();
                     clearTodos();

package/dist/ink/commands.js

@@ -24,6 +24,7 @@ export const SESSION_HELP = `commands:
   /stats     event counts for this session (local telemetry — nothing leaves this machine)
   /memory    show the durable facts the agent remembers about this project
   /cost      tokens, cache hit rate and estimated spend this session (local)
+  /mcp       list configured MCP servers + status; select one to authenticate / reconnect / disable
   /plan      toggle plan mode — research-only; the agent presents a plan you approve before any change
   /todos     show the agent's current task plan (it maintains one with todo_write on multi-step work)
   /bg        list background tasks this session (run_bash_background) and their status
@@ -40,6 +41,19 @@ export const SESSION_HELP = `commands:
 keys (at the prompt):
   Ctrl+R     reveal the model's thinking for the last answer (collapsed behind a spinner by default)
   Ctrl+T     reveal the folded tool-call trace for the last answer`;
+// Colored status word for an MCP server (shared by the Ink + readline /mcp UIs).
+export function mcpStatusText(info) {
+    switch (info.status) {
+        case "connected":
+            return chalk.green("connected");
+        case "needs-auth":
+            return chalk.yellow("needs auth");
+        case "failed":
+            return chalk.red("failed");
+        case "disabled":
+            return chalk.dim("disabled");
+    }
+}
 // Run a non-interactive command. Returns the note text to display, or null if
 // `line` isn't one of these (the App handles the rest).
 export function runInfoCommand(line, ctx) {

package/dist/mcp.js

@@ -1,7 +1,12 @@
 import { spawn } from "node:child_process"; // stdio servers are subprocesses
+import { createServer } from "node:http"; // the OAuth callback listener
+import crypto from "node:crypto"; // PKCE + state nonces
+import os from "node:os"; // home directory for token persistence
+import path from "node:path"; // path joining
+import fs from "node:fs"; // token file persistence
 import chalk from "chalk"; // status lines
 import { CONFIG } from "./config.js"; // configured servers
-import { registerExternalTool } from "./tools.js"; // expose discovered tools
+import { registerExternalTool, unregisterExternalTool } from "./tools.js"; // expose discovered tools
 import { emit } from "./telemetry.js"; // observability
 // MCP (Model Context Protocol) lets the agent borrow tools from external
 // servers — a filesystem server, a GitHub server, a database server, anything.
@@ -16,8 +21,44 @@ import { emit } from "./telemetry.js"; // observability
 //
 // Discovered tools are named mcp__<server>__<tool> so they never collide with
 // built-ins and the user can see (and gate) exactly where each came from.
+//
+// Since this file also drives the /mcp command, it keeps a REGISTRY of every
+// configured server and its live connection state (connected / failed /
+// needs-auth / disabled) so the UI can list them and reconnect/authenticate one
+// at a time — the way Claude Code's /mcp does.
+//
+// Remote servers (Linear, Slack, GitHub…) are OAuth-protected. The flow is the
+// MCP authorization spec end to end: the 401 challenge points at the resource
+// metadata (RFC 9728), which names the authorization server (RFC 8414); we
+// register a client dynamically (RFC 7591) unless the config carries a
+// pre-registered one; then authorization-code + PKCE with a loopback redirect,
+// the `resource` indicator (RFC 8707) on every token request, and refresh
+// tokens so a session survives token expiry without another browser round.
 const INIT_TIMEOUT_MS = 15_000; // a server that doesn't initialize in 15s is skipped
 const CALL_TIMEOUT_MS = 60_000; // a single tool call may take this long
+const OAUTH_CALLBACK_TIMEOUT_MS = 5 * 60_000; // how long the local callback waits for the browser
+const PROTOCOL_VERSION = "2024-11-05"; // the MCP revision we speak in the handshake
+const CLIENT_INFO = { name: "mini-agent", version: "0" }; // who we say we are in the handshake
+// Thrown when an HTTP MCP server answers 401 — the caller marks the server as
+// "needs auth" instead of "failed". The challenge header is parsed and kept:
+// it is the AUTHORITATIVE pointer to the OAuth metadata. Guessing well-known
+// paths is what breaks on servers like Slack, whose metadata sits at the origin
+// root rather than under the /mcp path.
+export class NeedsAuthError extends Error {
+    resourceMetadataUrl;
+    scope;
+    constructor(message, wwwAuthenticate) {
+        super(message);
+        this.name = "NeedsAuthError";
+        // The challenge is `Bearer key="value", key="value"…` — pull out the pairs we use.
+        for (const m of (wwwAuthenticate ?? "").matchAll(/(\w+)="([^"]*)"/g)) {
+            if (m[1] === "resource_metadata")
+                this.resourceMetadataUrl = m[2];
+            if (m[1] === "scope")
+                this.scope = m[2];
+        }
+    }
+}
 // ---- stdio transport: one JSON object per line, to a subprocess --------------
 class StdioTransport {
     child;
@@ -100,9 +141,11 @@ class HttpTransport {
     url;
     headers;
     sessionId; // assigned by the server on initialize, echoed on every later request
-    constructor(def) {
+    constructor(def, token) {
         this.url = def.url;
         this.headers = { ...def.headers };
+        if (token)
+            this.headers["authorization"] = `Bearer ${token}`; // OAuth access token
     }
     // The response to a POST may come back as a single JSON object OR as an SSE
     // stream carrying it. Either way we want the JSON-RPC message matching our id.
@@ -118,6 +161,9 @@ class HttpTransport {
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(timeoutMs),
         });
+        if (res.status === 401) {
+            throw new NeedsAuthError(`MCP server at ${this.url} requires authentication`, res.headers.get("www-authenticate"));
+        }
         const sid = res.headers.get("mcp-session-id"); // initialize hands us a session to keep
         if (sid)
             this.sessionId = sid;
@@ -143,6 +189,8 @@ class HttpTransport {
             return msg ?? { id: payload.id, error: { message: `MCP request '${payload.method}' returned no response` } };
         }
         catch (err) {
+            if (err instanceof NeedsAuthError)
+                throw err; // propagate so the registry can mark needs-auth
             return { id: payload.id, error: { message: `MCP HTTP request '${payload.method}' failed: ${err.message}` } };
         }
     }
@@ -150,6 +198,9 @@ class HttpTransport {
         // Fire-and-forget; errors on a notification are not worth surfacing.
         void this.post({ jsonrpc: "2.0", method, params }, INIT_TIMEOUT_MS, false).catch(() => { });
     }
+    setToken(token) {
+        this.headers["authorization"] = `Bearer ${token}`; // a refreshed token; the session id stays valid
+    }
     close() {
         // Best-effort: tell the server to drop the session. No await, no error care.
         if (this.sessionId) {
@@ -158,23 +209,23 @@ class HttpTransport {
     }
 }
 // Choose the pipe from the config: a url means HTTP, otherwise spawn over stdio.
-function makeTransport(def) {
-    return def.url ? new HttpTransport(def) : new StdioTransport(def);
+function makeTransport(def, token) {
+    return def.url ? new HttpTransport(def, token) : new StdioTransport(def);
 }
 // The protocol layer: handshake, request ids, tool flattening. It talks to a
 // Transport and is blind to whether that's a subprocess or an HTTP endpoint.
 class McpClient {
     transport;
     nextId = 1; // JSON-RPC request id counter
-    constructor(def) {
-        this.transport = makeTransport(def);
+    constructor(def, token) {
+        this.transport = makeTransport(def, token);
     }
     request(method, params, timeoutMs) {
         return this.transport.request({ jsonrpc: "2.0", id: this.nextId++, method, params }, timeoutMs);
     }
     // The MCP startup dance: initialize → initialized → list tools.
     async start() {
-        const init = await this.request("initialize", { protocolVersion: "2024-11-05", capabilities: {}, clientInfo: { name: "mini-agent", version: "0" } }, INIT_TIMEOUT_MS);
+        const init = await this.request("initialize", { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO }, INIT_TIMEOUT_MS);
         if (init.error)
             throw new Error(init.error.message); // server refused to initialize
         this.transport.notify("notifications/initialized", {}); // tell the server we're ready
@@ -192,46 +243,548 @@ class McpClient {
         const body = text || "(no output)";
         return res.result?.isError ? `[error] ${body}` : body; // MCP can flag a logical error in a successful response
     }
+    // Swap the bearer token after a refresh (a no-op for stdio).
+    setToken(token) {
+        this.transport.setToken?.(token);
+    }
     kill() {
         this.transport.close();
     }
 }
+const registry = new Map();
+// OAuth tokens persist to the global config dir so a reconnect across sessions
+// doesn't force the browser flow again. Plain JSON (self-hosted CLI, not a
+// hardened credential store — Claude Code uses the OS keychain); tokens are
+// bearer secrets — treat accordingly. Next to the tokens we keep everything a
+// refresh needs (token endpoint, client, resource) so it never rediscovers.
+// MINI_AGENT_OAUTH_STORE relocates the file (the test suite points it at a
+// scratch path so a fake server's tokens never land in the real store).
+const OAUTH_STORE_PATH = process.env.MINI_AGENT_OAUTH_STORE || path.join(os.homedir(), ".config", "mini-agent", "mcp-oauth.json");
+const expiryFrom = (t) => (typeof t.expires_in === "number" ? Date.now() + t.expires_in * 1000 : undefined);
+function readOAuthStore() {
+    try {
+        return JSON.parse(fs.readFileSync(OAUTH_STORE_PATH, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function writeOAuthStore(store) {
+    fs.mkdirSync(path.dirname(OAUTH_STORE_PATH), { recursive: true });
+    fs.writeFileSync(OAUTH_STORE_PATH, JSON.stringify(store, null, 2) + "\n");
+}
+const oauthStore = readOAuthStore();
+function base64url(input) {
+    return Buffer.from(input).toString("base64url");
+}
+function pkcePair() {
+    const verifier = base64url(crypto.randomBytes(32));
+    const challenge = base64url(crypto.createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+// Try to open a URL in the user's browser. Best-effort: if it fails, the caller
+// has already printed the link so the user can click it themselves. Set
+// MINI_AGENT_NO_BROWSER=1 to only print it (an SSH session, a test).
+function openBrowser(url) {
+    if (process.env.MINI_AGENT_NO_BROWSER)
+        return;
+    const platform = process.platform;
+    const cmd = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+    const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+    try {
+        const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        /* ignore — the printed URL is the fallback */
+    }
+}
+async function fetchJson(url) {
+    try {
+        const res = await fetch(url, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(INIT_TIMEOUT_MS) });
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}
+// Ask the server for its 401 challenge without a token — the cheapest way to
+// learn where the metadata lives when no 401 was recorded this session (a
+// re-authenticate while still connected). Empty when the server doesn't 401.
+async function probeChallenge(serverUrl) {
+    try {
+        const res = await fetch(serverUrl, {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json, text/event-stream" },
+            body: JSON.stringify({ jsonrpc: "2.0", id: 0, method: "initialize", params: { protocolVersion: PROTOCOL_VERSION, capabilities: {}, clientInfo: CLIENT_INFO } }),
+            signal: AbortSignal.timeout(INIT_TIMEOUT_MS),
+        });
+        if (res.status === 401)
+            return new NeedsAuthError("", res.headers.get("www-authenticate"));
+    }
+    catch {
+        /* unreachable server — discovery falls back to the well-known paths */
+    }
+    return {};
+}
+// Discover the OAuth endpoints for an MCP server: protected-resource metadata
+// (RFC 9728) → authorization-server metadata (RFC 8414). The 401 challenge says
+// exactly where the resource metadata lives; the well-known paths under the
+// server's origin are a fallback for servers that don't send one. Exported so
+// the discovery step can be exercised on its own. Returns null when the server
+// has no OAuth metadata at all.
+export async function discoverOAuth(serverUrl, challenge = {}) {
+    const base = new URL(serverUrl);
+    const rsPath = base.pathname === "/" ? "" : base.pathname.replace(/\/$/, "");
+    const candidates = [
+        challenge.resourceMetadataUrl, // what the server told us — authoritative
+        `${base.origin}/.well-known/oauth-protected-resource${rsPath}`, // RFC 9728 path-scoped (Linear)
+        `${base.origin}/.well-known/oauth-protected-resource`, // RFC 9728 origin-wide (Slack)
+    ].filter((u) => Boolean(u));
+    let prm = null;
+    for (const url of new Set(candidates)) {
+        prm = await fetchJson(url);
+        if (prm)
+            break;
+    }
+    // The resource names its authorization server(s); default to the origin. A
+    // server with a path component would need the RFC 8414 path insertion — none
+    // of the servers we target has one, so keep it simple.
+    const authServers = Array.isArray(prm?.authorization_servers) ? prm.authorization_servers : [];
+    const authServer = (authServers[0] ?? base.origin).replace(/\/$/, "");
+    // RFC 8414 first, then the OpenID Connect location some servers use instead.
+    const metadata = (await fetchJson(`${authServer}/.well-known/oauth-authorization-server`)) ?? (await fetchJson(`${authServer}/.well-known/openid-configuration`));
+    if (!metadata)
+        return null;
+    const str = (v) => (typeof v === "string" ? v : undefined);
+    const list = (v) => (Array.isArray(v) && v.length ? v : undefined);
+    const authorizationEndpoint = str(metadata.authorization_endpoint);
+    const tokenEndpoint = str(metadata.token_endpoint);
+    if (!authorizationEndpoint || !tokenEndpoint)
+        return null;
+    return {
+        authorizationEndpoint,
+        tokenEndpoint,
+        registrationEndpoint: str(metadata.registration_endpoint),
+        scopes: challenge.scope?.split(/\s+/).filter(Boolean) ?? list(prm?.scopes_supported) ?? list(metadata.scopes_supported),
+        resource: str(prm?.resource) ?? serverUrl,
+    };
+}
+// Bind the loopback listener for the authorization-code redirect. The browser
+// is sent to http://localhost:<port>/callback (the redirect URI Claude Code
+// registers too, so a pre-registered Slack client id works unchanged), and
+// "localhost" may resolve to 127.0.0.1 or ::1 depending on browser and OS — so
+// listen on both; the IPv6 bind is best-effort. `port` 0 = any free port (the
+// DCR case, where we register whatever we got); a fixed port is what a
+// pre-registered client demands. The code promise is armed on creation, BEFORE
+// the browser opens, so a fast callback can't race us.
+async function listenForCallback(port, state) {
+    let settle;
+    const handler = (req, res) => {
+        const url = new URL(req.url ?? "/", "http://localhost");
+        res.setHeader("connection", "close"); // one-shot listener: a kept-alive socket would deliver a LATER flow's callback (same fixed port) to this dead handler
+        if (url.pathname !== "/callback" || url.searchParams.get("state") !== state)
+            return void res.writeHead(404).end(); // not ours (favicon, a stale tab…)
+        res.setHeader("content-type", "text/html");
+        res.end("<h1>Connected</h1><p>You can close this window and return to the terminal.</p>");
+        // Settle only once the page has been flushed: settling tears the servers
+        // down, and tearing down before the write lands would blank the browser tab.
+        res.once("finish", () => {
+            const code = url.searchParams.get("code");
+            if (code)
+                settle?.resolve(code);
+            else
+                settle?.reject(new Error(`OAuth callback did not include a code: ${url.searchParams.get("error_description") ?? url.searchParams.get("error") ?? "unknown error"}`));
+        });
+    };
+    const v4 = createServer(handler);
+    const bound = await new Promise((resolve, reject) => {
+        v4.once("error", (err) => reject(new Error(`Could not bind the OAuth callback on port ${port || "(any)"}: ${err.message}`)));
+        v4.listen(port, "127.0.0.1", () => {
+            const addr = v4.address();
+            resolve(addr && typeof addr === "object" ? addr.port : port);
+        });
+    });
+    const v6 = createServer(handler);
+    await new Promise((resolve) => {
+        v6.once("error", () => resolve()); // no IPv6 loopback here — the v4 listener carries it
+        v6.listen(bound, "::1", () => resolve());
+    });
+    const close = () => {
+        // Release the port for real: close() alone leaves open sockets alive, and a
+        // pre-registered client's next flow needs the SAME port back immediately.
+        for (const s of [v4, v6]) {
+            s.closeAllConnections();
+            s.close();
+        }
+    };
+    const code = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            close();
+            reject(new Error("Timed out waiting for OAuth authorization in the browser"));
+        }, OAUTH_CALLBACK_TIMEOUT_MS);
+        settle = {
+            resolve: (c) => (clearTimeout(timer), close(), resolve(c)),
+            reject: (e) => (clearTimeout(timer), close(), reject(e)),
+        };
+    });
+    return { port: bound, close, code };
+}
+// Run the OAuth authorization-code flow for an HTTP server: PKCE always;
+// dynamic client registration (RFC 7591) unless the config carries a
+// pre-registered client; a loopback redirect; then the code → token exchange
+// with the `resource` indicator (RFC 8707). When onUrl is provided, the
+// authorization URL is handed back so the UI can print it in case the browser
+// doesn't open. Resolves with everything the store needs to reconnect + refresh.
+async function runOAuthFlow(def, challenge, onUrl) {
+    if (!def.url)
+        throw new Error("OAuth is only available for http MCP servers");
+    const discovery = await discoverOAuth(def.url, challenge);
+    if (!discovery)
+        throw new Error(`No OAuth metadata found for ${def.url}`);
+    const pkce = pkcePair();
+    const state = base64url(crypto.randomBytes(16));
+    // The redirect URI must match what the client registered: for DCR we register
+    // whatever port we were given; a pre-registered client (Slack) fixes the port.
+    const listener = await listenForCallback(def.oauth?.callbackPort ?? 0, state);
+    listener.code.catch(() => { }); // settled later; never an unhandled rejection if we throw before awaiting it
+    const redirectUri = `http://localhost:${listener.port}/callback`;
+    let clientId = def.oauth?.clientId ?? ""; // a pre-registered client skips DCR
+    let clientSecret = def.oauth?.clientSecret;
+    if (!clientId && discovery.registrationEndpoint) {
+        // Dynamic client registration — most MCP servers register a public client on the spot.
+        const regRes = await fetch(discovery.registrationEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify({
+                redirect_uris: [redirectUri],
+                token_endpoint_auth_method: "none",
+                grant_types: ["authorization_code", "refresh_token"],
+                response_types: ["code"],
+                client_name: "mini-agent",
+            }),
+            signal: AbortSignal.timeout(INIT_TIMEOUT_MS),
+        }).catch((err) => {
+            throw new Error(`OAuth client registration failed for ${def.url}: ${err.message}`);
+        });
+        if (regRes.ok) {
+            const reg = (await regRes.json());
+            clientId = reg.client_id ?? "";
+            clientSecret = reg.client_secret;
+        }
+    }
+    if (!clientId) {
+        listener.close();
+        throw new Error(discovery.registrationEndpoint
+            ? `OAuth client registration failed for ${def.url}`
+            : `${def.url} offers no dynamic client registration — set mcpServers.<name>.oauth.clientId (and callbackPort) to a pre-registered client`);
+    }
+    const authUrl = new URL(discovery.authorizationEndpoint);
+    authUrl.searchParams.set("response_type", "code");
+    authUrl.searchParams.set("client_id", clientId);
+    authUrl.searchParams.set("code_challenge", pkce.challenge);
+    authUrl.searchParams.set("code_challenge_method", "S256");
+    authUrl.searchParams.set("redirect_uri", redirectUri);
+    authUrl.searchParams.set("state", state);
+    authUrl.searchParams.set("resource", discovery.resource); // RFC 8707: bind the token to THIS server
+    const scopes = def.oauth?.scopes ?? discovery.scopes; // an explicit config list wins over what the server advertises
+    if (scopes?.length)
+        authUrl.searchParams.set("scope", scopes.join(" "));
+    onUrl?.(authUrl.href);
+    openBrowser(authUrl.href);
+    const code = await listener.code; // the listener closes itself once settled
+    const params = new URLSearchParams({
+        grant_type: "authorization_code",
+        code,
+        code_verifier: pkce.verifier,
+        redirect_uri: redirectUri,
+        client_id: clientId,
+        resource: discovery.resource,
+    });
+    if (clientSecret)
+        params.set("client_secret", clientSecret);
+    const tokenRes = await fetch(discovery.tokenEndpoint, {
+        method: "POST",
+        headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+        body: params.toString(),
+        signal: AbortSignal.timeout(INIT_TIMEOUT_MS),
+    });
+    if (!tokenRes.ok) {
+        throw new Error(`OAuth token exchange failed: HTTP ${tokenRes.status} ${(await tokenRes.text()).slice(0, 200)}`);
+    }
+    const tokens = (await tokenRes.json());
+    if (!tokens.access_token)
+        throw new Error(`OAuth token exchange returned no access_token: ${tokens.error_description ?? tokens.error ?? "unknown error"}`);
+    return {
+        accessToken: tokens.access_token,
+        refreshToken: tokens.refresh_token,
+        expiresAt: expiryFrom(tokens),
+        clientId,
+        clientSecret,
+        tokenEndpoint: discovery.tokenEndpoint,
+        resource: discovery.resource,
+    };
+}
+function entryFor(name) {
+    let entry = registry.get(name);
+    if (!entry) {
+        const def = CONFIG.mcpServers[name];
+        if (!def)
+            throw new Error(`No MCP server named "${name}"`);
+        entry = { def, status: "failed", tools: 0, toolNames: [] };
+        registry.set(name, entry);
+    }
+    return entry;
+}
+function registerTools(name, specs, client) {
+    for (const spec of specs) {
+        const toolName = `mcp__${name}__${spec.name}`; // namespaced, collision-proof
+        const tool = {
+            definition: {
+                type: "function",
+                function: {
+                    name: toolName,
+                    description: `[MCP:${name}] ${spec.description ?? spec.name}`, // mark the origin in the manual
+                    parameters: spec.inputSchema ?? { type: "object", properties: {} }, // pass the server's schema straight through
+                },
+            },
+            // dispatch routes here; the permission gate ran first. A 401 mid-session
+            // (the access token expired or was revoked) gets ONE silent refresh and a
+            // retry; if that fails the server is flagged needs-auth and the model gets
+            // a readable error pointing at /mcp auth — a tool result never throws.
+            run: async (args) => {
+                try {
+                    return await client.callTool(spec.name, args);
+                }
+                catch (err) {
+                    if (!(err instanceof NeedsAuthError))
+                        throw err; // dispatch turns any other crash into text
+                    const fresh = await refreshAccessToken(name);
+                    if (fresh) {
+                        client.setToken(fresh);
+                        try {
+                            return await client.callTool(spec.name, args);
+                        }
+                        catch (again) {
+                            if (!(again instanceof NeedsAuthError))
+                                throw again;
+                        }
+                    }
+                    markNeedsAuth(name, err);
+                    return `[error] MCP server "${name}" needs authentication — run /mcp auth ${name}`;
+                }
+            },
+        };
+        registerExternalTool(tool); // now indistinguishable from a built-in to the rest of the system
+    }
+    return specs.length;
+}
+// Flag a server as needing the browser flow and remember the challenge so
+// /mcp auth knows where the OAuth metadata lives. Its tools stay registered:
+// they answer with the readable error until the user authenticates.
+function markNeedsAuth(name, challenge) {
+    const entry = entryFor(name);
+    entry.status = "needs-auth";
+    entry.error = challenge.message;
+    entry.challenge = challenge;
+}
+// Connect a single configured server and register its tools. Updates the
+// registry with the live status. Used by connectMcpServers() at startup and by
+// /mcp reconnect / enable / auth.
+async function connectOne(name, retried = false) {
+    const entry = entryFor(name);
+    // Unregister any stale tools from a previous connection.
+    for (const n of entry.toolNames)
+        unregisterExternalTool(n);
+    entry.toolNames = [];
+    entry.client?.kill();
+    entry.client = undefined;
+    // A stored token we KNOW is expired is refreshed before connecting rather
+    // than burning a 401 round trip on it.
+    let stored = oauthStore[name];
+    if (stored?.refreshToken && stored.expiresAt && stored.expiresAt <= Date.now()) {
+        await refreshAccessToken(name);
+        stored = oauthStore[name];
+    }
+    const client = new McpClient(entry.def, stored?.accessToken);
+    try {
+        const specs = await client.start(); // handshake + discover
+        entry.client = client;
+        entry.tools = registerTools(name, specs, client);
+        entry.toolNames = specs.map((s) => `mcp__${name}__${s.name}`);
+        entry.status = "connected";
+        entry.error = undefined;
+        emit("agent_mcp_connected", { server: name, tools: specs.length, transport: entry.def.url ? "http" : "stdio" });
+        console.log(chalk.dim(`(mcp: ${name} — ${specs.length} tools${entry.def.url ? " over http" : ""})`)); // visible at startup / on reconnect
+    }
+    catch (err) {
+        client.kill(); // don't leak the process/session
+        if (err instanceof NeedsAuthError) {
+            // A stale token (expired early, revoked): one refresh + retry before giving up.
+            if (!retried && stored?.refreshToken && (await refreshAccessToken(name)))
+                return connectOne(name, true);
+            markNeedsAuth(name, err);
+        }
+        else {
+            entry.status = "failed";
+            entry.error = err.message;
+        }
+        emit("agent_mcp_failed", { server: name });
+        console.error(chalk.yellow(`  [mcp] ${name} ${entry.status === "needs-auth" ? `needs authentication (run /mcp auth ${name})` : "failed to start"}: ${err.message}`));
+    }
+}
 // Connect to every configured MCP server, register their tools, and return a
 // cleanup function. Failures are isolated: a server that won't start is logged
 // and skipped — it never stops the agent or the other servers.
 export async function connectMcpServers() {
-    const entries = Object.entries(CONFIG.mcpServers); // [name, def] pairs
-    if (!entries.length)
-        return () => { }; // the common case: nothing configured
-    const clients = []; // for cleanup
-    for (const [serverName, def] of entries) {
-        const client = new McpClient(def);
-        try {
-            const specs = await client.start(); // handshake + discover
-            clients.push(client);
-            for (const spec of specs) {
-                const toolName = `mcp__${serverName}__${spec.name}`; // namespaced, collision-proof
-                const tool = {
-                    definition: {
-                        type: "function",
-                        function: {
-                            name: toolName,
-                            description: `[MCP:${serverName}] ${spec.description ?? spec.name}`, // mark the origin in the manual
-                            parameters: spec.inputSchema ?? { type: "object", properties: {} }, // pass the server's schema straight through
-                        },
-                    },
-                    run: async (args) => client.callTool(spec.name, args), // dispatch routes here; the permission gate ran first
-                };
-                registerExternalTool(tool); // now indistinguishable from a built-in to the rest of the system
-            }
-            emit("agent_mcp_connected", { server: serverName, tools: specs.length, transport: def.url ? "http" : "stdio" });
-            console.log(chalk.dim(`(mcp: ${serverName} — ${specs.length} tools${def.url ? " over http" : ""})`)); // visible at startup
-        }
-        catch (err) {
-            client.kill(); // don't leak the process/session
-            emit("agent_mcp_failed", { server: serverName });
-            console.error(chalk.yellow(`  [mcp] ${serverName} failed to start (skipped): ${err.message}`)); // loud, but not fatal
-        }
+    const entries = Object.keys(CONFIG.mcpServers); // configured server names
+    for (const name of entries) {
+        await connectOne(name); // sequential: a slow start doesn't starve the next one
+    }
+    return () => {
+        for (const entry of registry.values())
+            entry.client?.kill(); // cleanup on exit
+    };
+}
+// ---- /mcp command support ----------------------------------------------------
+export function listMcpServers() {
+    // Include every CONFIGURED server, even ones never attempted this session.
+    return Object.entries(CONFIG.mcpServers).map(([name, def]) => {
+        const entry = registry.get(name);
+        return {
+            name,
+            transport: def.url ? "http" : "stdio",
+            status: entry?.status ?? "failed",
+            tools: entry?.tools ?? 0,
+            error: entry?.error,
+            authenticated: Boolean(oauthStore[name]?.accessToken),
+            url: def.url,
+        };
+    });
+}
+// Which actions make sense for a server in a given state. Mirrors Claude Code's
+// per-server menu: authenticate when it needs auth, reconnect when it isn't,
+// enable/disable to toggle it off/on.
+export function mcpActionsFor(info) {
+    if (info.status === "disabled") {
+        return [{ label: "Enable", action: "enable" }];
+    }
+    const out = [];
+    if (info.transport === "http") {
+        out.push({ label: info.authenticated ? "Re-authenticate" : "Authenticate", action: "authenticate" });
+    }
+    out.push({ label: "Reconnect", action: "reconnect" });
+    out.push({ label: "Disable", action: "disable" });
+    return out;
+}
+// Trade the stored refresh token for a new access token, at the token endpoint
+// recorded when the user authenticated — no rediscovery. A definitive rejection
+// (400/401: the refresh token itself is dead) wipes the record so the UI tells
+// the truth: the user has to authenticate again. Network trouble keeps it.
+// Returns the new access token, or undefined when there is none to be had.
+async function refreshAccessToken(name) {
+    const stored = oauthStore[name];
+    if (!stored?.refreshToken || !stored.tokenEndpoint)
+        return undefined;
+    const params = new URLSearchParams({ grant_type: "refresh_token", refresh_token: stored.refreshToken });
+    if (stored.clientId)
+        params.set("client_id", stored.clientId);
+    if (stored.clientSecret)
+        params.set("client_secret", stored.clientSecret);
+    if (stored.resource)
+        params.set("resource", stored.resource);
+    let res;
+    try {
+        res = await fetch(stored.tokenEndpoint, {
+            method: "POST",
+            headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+            body: params.toString(),
+            signal: AbortSignal.timeout(INIT_TIMEOUT_MS),
+        });
+    }
+    catch {
+        return undefined; // offline / timeout — keep the record, it may work next time
+    }
+    if (res.status === 400 || res.status === 401) {
+        delete oauthStore[name]; // invalid_grant: the refresh token is gone for good
+        writeOAuthStore(oauthStore);
+        return undefined;
+    }
+    if (!res.ok)
+        return undefined; // a server hiccup — keep the record
+    const tokens = (await res.json().catch(() => ({})));
+    if (!tokens.access_token)
+        return undefined;
+    oauthStore[name] = { ...stored, accessToken: tokens.access_token, refreshToken: tokens.refresh_token ?? stored.refreshToken, expiresAt: expiryFrom(tokens) };
+    writeOAuthStore(oauthStore);
+    return tokens.access_token;
+}
+// Authenticate a server via browser OAuth and store the tokens. Returns a
+// human-readable result for the UI.
+export async function authenticateMcpServer(name, onUrl) {
+    const def = CONFIG.mcpServers[name];
+    if (!def)
+        return `No MCP server named "${name}"`;
+    if (!def.url)
+        return `${name} is a stdio server — it needs no OAuth authentication`;
+    // Where the OAuth metadata lives: the last 401 told us; if none was seen this
+    // session (re-authenticating while connected), ask the server now.
+    const entry = entryFor(name);
+    const challenge = entry.challenge ?? (await probeChallenge(def.url));
+    oauthStore[name] = await runOAuthFlow(def, challenge, onUrl);
+    writeOAuthStore(oauthStore);
+    // Immediately reconnect with the fresh token so the server shows connected.
+    await connectOne(name);
+    const status = entry.status;
+    return status === "connected"
+        ? `Authentication successful. Connected to ${name}.`
+        : `Authentication done, but ${name} is ${status} — use /mcp reconnect ${name} to retry.`;
+}
+// Disconnect and reconnect a single server (re-registering its tools). A stale
+// stored token is refreshed inside connectOne, so this is just: connect again.
+export async function reconnectMcpServer(name) {
+    const def = CONFIG.mcpServers[name];
+    if (!def)
+        return `No MCP server named "${name}"`;
+    await connectOne(name);
+    const info = listMcpServers().find((s) => s.name === name);
+    return info.status === "connected"
+        ? `Connected to ${name} (${info.tools} tool${info.tools === 1 ? "" : "s"}).`
+        : `${name} is ${info.status}: ${info.error ?? "unknown error"}`;
+}
+// Toggle a server off/on (session-only — the config file is not rewritten).
+export async function disableMcpServer(name) {
+    const entry = entryFor(name);
+    for (const n of entry.toolNames)
+        unregisterExternalTool(n);
+    entry.toolNames = [];
+    entry.client?.kill();
+    entry.client = undefined;
+    entry.status = "disabled";
+    entry.error = undefined;
+    return `Disabled ${name}.`;
+}
+export async function enableMcpServer(name) {
+    const entry = entryFor(name);
+    if (entry.status !== "disabled")
+        return `${name} is not disabled.`;
+    await connectOne(name);
+    const info = listMcpServers().find((s) => s.name === name);
+    return info.status === "connected" ? `Enabled ${name}.` : `${name} is ${info.status}: ${info.error ?? "unknown error"}`;
+}
+// Run one action from mcpActionsFor and return the note to display.
+export async function runMcpAction(name, action, onUrl) {
+    switch (action) {
+        case "authenticate":
+            return authenticateMcpServer(name, onUrl);
+        case "reconnect":
+            return reconnectMcpServer(name);
+        case "disable":
+            return disableMcpServer(name);
+        case "enable":
+            return enableMcpServer(name);
     }
-    return () => clients.forEach((c) => c.kill()); // the caller calls this on exit
 }

package/dist/session.js

@@ -15,16 +15,17 @@ export function newSessionId() {
 // history is not append-only — compaction rewrites it — so a snapshot is the
 // only representation that is always correct. Crash mid-write leaves the
 // previous snapshot intact.
-export function saveSession(id, model, messages) {
+export function saveSession(id, model, messages, title) {
     const dir = sessionsDir();
     fs.mkdirSync(dir, { recursive: true }); // first save creates the directory
     const file = path.join(dir, `${id}.json`); // the real destination
-    const existing = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null; // to preserve startedAt
+    const existing = fs.existsSync(file) ? JSON.parse(fs.readFileSync(file, "utf8")) : null; // to preserve startedAt + title
     const data = {
         id,
         startedAt: existing?.startedAt ?? new Date().toISOString(), // first save stamps it, later saves keep it
         savedAt: new Date().toISOString(), // always refreshed
         model, // informational — resume does not force the same model
+        title: title ?? existing?.title, // a generated title sticks across saves
         messages: messages.filter((m) => m.role !== "system"), // the constitution is rebuilt fresh on resume (AGENT.md may have changed)
     };
     const tmp = `${file}.tmp`; // write next to the destination (same filesystem → rename is atomic)
@@ -32,6 +33,23 @@ export function saveSession(id, model, messages) {
     fs.renameSync(tmp, file); // atomic swap
     prune(); // keep the directory bounded
 }
+// Overwrite just the title of an existing session. Used when the title model
+// finishes AFTER the first save — the next saveSession would otherwise drop it.
+export function setSessionTitle(id, title) {
+    const file = path.join(sessionsDir(), `${id}.json`);
+    let s;
+    try {
+        s = JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return; // the session hasn't been saved yet — the title will land on the next save
+    }
+    s.title = title;
+    s.savedAt = new Date().toISOString(); // a title is a change; keep the list ordering honest
+    const tmp = `${file}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(s)); // atomic, same as saveSession
+    fs.renameSync(tmp, file);
+}
 // Session files on disk, newest (most recently saved) first. Shared by every
 // reader below. Skips tmp files and strangers.
 function sessionFilesNewestFirst() {
@@ -69,7 +87,8 @@ export function loadSession(id) {
 // A one-line, human-readable title for a session: the first thing the user
 // actually typed, with any @file attachment block stripped off and the text
 // flattened to a single trimmed line. This is what makes a session list
-// pickable instead of a wall of timestamps.
+// pickable instead of a wall of timestamps. It's the FALLBACK when no concise
+// generated title has been stored (see saveSession title + setSessionTitle).
 export function sessionTitle(messages) {
     const firstUser = messages.find((m) => m.role === "user");
     let text = typeof firstUser?.content === "string" ? firstUser.content : "";
@@ -86,7 +105,7 @@ export function listSessions(limit = 10) {
             break;
         try {
             const s = JSON.parse(fs.readFileSync(path.join(sessionsDir(), f), "utf8"));
-            out.push({ id: s.id, savedAt: s.savedAt, model: s.model, messageCount: s.messages.length, title: sessionTitle(s.messages) });
+            out.push({ id: s.id, savedAt: s.savedAt, model: s.model, messageCount: s.messages.length, title: s.title ?? sessionTitle(s.messages) });
         }
         catch {
             /* skip a corrupt file */

package/dist/title.js

@@ -0,0 +1,49 @@
+// One cheap model call that turns the user's first prompt into a short,
+// pickable session name — the same idea Claude Code uses (a Haiku-tier call
+// producing a 3-7 word sentence-case title, stored as the session's aiTitle).
+// It runs once, fire-and-forget, after the first real user message, so it never
+// blocks the turn and a failure silently falls back to the raw first prompt.
+const TITLE_SYSTEM = `Generate a concise, sentence-case title (3-7 words) that captures the main topic or goal of the user's request. The title should be clear enough that the user recognizes the session in a list. Use sentence case: capitalize only the first word and proper nouns.
+Return ONLY the title — no quotes, no leading/trailing punctuation, no explanation.
+
+Good examples:
+Fix login button on mobile
+Add OAuth authentication
+Debug failing CI tests
+Refactor API client error handling
+
+Bad (too vague): Code changes
+Bad (too long): Investigate and fix the issue where the login button does not respond on mobile devices
+Bad (wrong case): Fix Login Button On Mobile`;
+// Strip the model's inevitable chatter: surrounding quotes, trailing periods,
+// markdown fences, and any multi-line prose. Pure + lenient on purpose.
+export function cleanSessionTitle(text) {
+    let t = text.replace(/^```[^\n]*\n?|\n?```$/g, ""); // drop a markdown fence if present
+    t = t.split("\n")[0] ?? ""; // first line only
+    t = t.replace(/^[\s"'“”‘’]+|[\s"'“”‘’.。]+$/g, "").trim(); // strip quotes + trailing punctuation
+    return t.replace(/\s+/g, " ").trim();
+}
+// Generate a session title from the first user message. Returns null on any
+// failure (bad model response, network error) — callers fall back to the prompt.
+export async function generateSessionTitle(client, model, firstPrompt) {
+    const trimmed = firstPrompt.replace(/\s+/g, " ").trim();
+    if (!trimmed)
+        return null;
+    let text = "";
+    try {
+        const res = await client.chat.completions.create({
+            model,
+            messages: [
+                { role: "system", content: TITLE_SYSTEM },
+                { role: "user", content: trimmed },
+            ],
+            stream: false,
+        });
+        text = res.choices?.[0]?.message?.content ?? "";
+    }
+    catch {
+        return null; // a failed title must never surface or break the session
+    }
+    const title = cleanSessionTitle(text);
+    return title || null;
+}

package/dist/tools.js

@@ -412,6 +412,11 @@ export const tools = {
 export function registerExternalTool(tool) {
     tools[tool.definition.function.name] = tool;
 }
+// Remove an external tool by name (used when an MCP server is disconnected or
+// reconnected — its stale tools must never stay registered under the same name).
+export function unregisterExternalTool(name) {
+    delete tools[name];
+}
 // The manuals sent to the model. A function (not a const) since Day 15: MCP
 // tools register after module load, so the list must be computed when asked.
 export function toolDefinitions() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-from-zero",
-  "version": "0.33.1",
+  "version": "0.34.0",
   "description": "Build a Claude Code-style CLI agent from scratch, with AI as your pair programmer — companion code for a 10-day tutorial (DeepSeek by default, any OpenAI-compatible model)",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
     "eval": "tsx --env-file=.env eval/run.ts",
     "build": "tsc -p tsconfig.build.json",
     "prepare": "npm run build",
-    "test": "tsx tests/tools.test.ts && tsx tests/permissions.test.ts && tsx tests/context.test.ts && tsx tests/hooks.test.ts && tsx tests/mcp.test.ts && tsx tests/judge.test.ts && tsx tests/memory.test.ts && tsx tests/cost.test.ts && tsx tests/validate.test.ts && tsx tests/plan.test.ts && tsx tests/diff.test.ts && tsx tests/undo.test.ts && tsx tests/tiering.test.ts && tsx tests/mcp-http.test.ts && tsx tests/changes.test.ts && tsx tests/mentions.test.ts && tsx tests/session.test.ts && tsx tests/ui.test.ts && tsx tests/approval.test.ts && tsx tests/form.test.ts && tsx tests/model.test.ts && tsx tests/reasoning.test.ts && tsx tests/skills.test.ts && tsx tests/markdown.test.ts && tsx tests/editor.test.ts && tsx tests/todos.test.ts && tsx tests/background.test.ts && tsx tests/team.test.ts && tsx tests/board.test.ts && tsx tests/drop.test.ts && tsx tests/editline.test.ts && tsx tests/cron.test.ts"
+    "test": "tsx tests/tools.test.ts && tsx tests/permissions.test.ts && tsx tests/context.test.ts && tsx tests/hooks.test.ts && tsx tests/mcp.test.ts && tsx tests/judge.test.ts && tsx tests/memory.test.ts && tsx tests/cost.test.ts && tsx tests/validate.test.ts && tsx tests/plan.test.ts && tsx tests/diff.test.ts && tsx tests/undo.test.ts && tsx tests/tiering.test.ts && tsx tests/mcp-http.test.ts && tsx tests/mcp-oauth.test.ts && tsx tests/changes.test.ts && tsx tests/mentions.test.ts && tsx tests/session.test.ts && tsx tests/ui.test.ts && tsx tests/approval.test.ts && tsx tests/form.test.ts && tsx tests/model.test.ts && tsx tests/reasoning.test.ts && tsx tests/skills.test.ts && tsx tests/markdown.test.ts && tsx tests/editor.test.ts && tsx tests/todos.test.ts && tsx tests/background.test.ts && tsx tests/team.test.ts && tsx tests/board.test.ts && tsx tests/drop.test.ts && tsx tests/editline.test.ts && tsx tests/cron.test.ts"
   },
   "engines": {
     "node": ">=20.6"