agent-from-zero 0.35.1 → 0.35.3

package/dist/mcp.js

@@ -5,7 +5,7 @@ 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 { CONFIG, GLOBAL_SETTINGS_PATH, PROJECT_SETTINGS_PATH, mcpConfigPath, readMcpServers } from "./config.js"; // configured servers + hot reload
 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
@@ -82,6 +82,7 @@ class StdioTransport {
         });
         this.child.stderr.on("data", () => { }); // the server's stderr is its own logging — never our stdout
     }
+    onNotification;
     onMessage(line) {
         let msg;
         try {
@@ -90,6 +91,15 @@ class StdioTransport {
         catch {
             return; // ignore anything that isn't valid JSON-RPC
         }
+        if (msg.method) {
+            if (msg.id === undefined)
+                return this.onNotification?.(msg.method, msg.params); // e.g. tools/list_changed
+            // A server→client request. We answer ping (the spec's liveness check) and
+            // refuse the rest — an unanswered request would leave the server waiting.
+            const reply = msg.method === "ping" ? { result: {} } : { error: { code: -32601, message: `Method not found: ${msg.method}` } };
+            this.child.stdin.write(JSON.stringify({ jsonrpc: "2.0", id: msg.id, ...reply }) + "\n");
+            return;
+        }
         const resolver = this.pending.get(msg.id);
         if (resolver) {
             this.pending.delete(msg.id);
@@ -141,6 +151,8 @@ class HttpTransport {
     url;
     headers;
     sessionId; // assigned by the server on initialize, echoed on every later request
+    listening; // the standalone GET stream, if open
+    onNotification;
     constructor(def, token) {
         this.url = def.url;
         this.headers = { ...def.headers };
@@ -171,17 +183,82 @@ class HttpTransport {
             return null; // a notification expects no body (202 Accepted)
         const raw = await res.text();
         const payloads = res.headers.get("content-type")?.includes("text/event-stream") ? parseSseData(raw) : [raw];
+        let response = null;
         for (const p of payloads) {
+            // An SSE response may carry server notifications BEFORE the response we
+            // came for (Streamable HTTP allows it) — deliver those, keep looking.
+            if (this.deliver(p))
+                continue;
             try {
                 const msg = JSON.parse(p);
-                if (msg && (msg.result !== undefined || msg.error !== undefined))
-                    return msg; // the response we came for
+                if (!response && msg && (msg.result !== undefined || msg.error !== undefined))
+                    response = msg; // the response we came for
             }
             catch {
                 /* skip non-JSON frames (SSE comments, keep-alives) */
             }
         }
-        return null;
+        return response;
+    }
+    // Hand one raw payload to onNotification if it is a server notification.
+    // Returns true when it was one (so the caller doesn't treat it as a response).
+    deliver(raw) {
+        try {
+            const msg = JSON.parse(raw);
+            if (!msg?.method || msg.id !== undefined)
+                return false;
+            this.onNotification?.(msg.method, msg.params);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // Streamable HTTP's server→client channel: a long-lived GET that the server
+    // writes SSE frames into whenever it wants — that's where list_changed
+    // arrives between our requests. A server without one answers 405; then
+    // notifications can still ride along on POST responses (above). A dropped
+    // stream reconnects with backoff; one that keeps dying quickly gives up.
+    listen() {
+        if (this.listening)
+            return;
+        const ctrl = (this.listening = new AbortController());
+        const run = async (attempt) => {
+            const started = Date.now();
+            try {
+                const res = await fetch(this.url, {
+                    method: "GET",
+                    headers: { accept: "text/event-stream", ...(this.sessionId ? { "mcp-session-id": this.sessionId } : {}), ...this.headers },
+                    signal: ctrl.signal,
+                });
+                if (!res.ok || !res.body || !res.headers.get("content-type")?.includes("text/event-stream"))
+                    return; // no standalone stream (405 etc.) — not an error
+                const reader = res.body.getReader();
+                const decoder = new TextDecoder();
+                let buf = "";
+                for (;;) {
+                    const { value, done } = await reader.read();
+                    if (done)
+                        break;
+                    buf += decoder.decode(value, { stream: true });
+                    const frames = buf.split(/\r?\n\r?\n/);
+                    buf = frames.pop() ?? ""; // an incomplete frame waits for the next chunk
+                    for (const frame of frames)
+                        for (const data of parseSseData(frame))
+                            this.deliver(data);
+                }
+            }
+            catch {
+                if (ctrl.signal.aborted)
+                    return; // closed on purpose
+            }
+            if (ctrl.signal.aborted)
+                return;
+            const next = Date.now() - started > 30_000 ? 0 : attempt + 1; // a stream that lived a while resets the backoff
+            if (next < 5)
+                setTimeout(() => void run(next), 1000 * 2 ** next).unref(); // never keeps the process alive
+        };
+        void run(0);
     }
     async request(payload, timeoutMs) {
         try {
@@ -202,6 +279,7 @@ class HttpTransport {
         this.headers["authorization"] = `Bearer ${token}`; // a refreshed token; the session id stays valid
     }
     close() {
+        this.listening?.abort(); // stop the event stream first
         // Best-effort: tell the server to drop the session. No await, no error care.
         if (this.sessionId) {
             void fetch(this.url, { method: "DELETE", headers: { "mcp-session-id": this.sessionId, ...this.headers } }).catch(() => { });
@@ -217,8 +295,15 @@ function makeTransport(def, token) {
 class McpClient {
     transport;
     nextId = 1; // JSON-RPC request id counter
+    onToolsChanged; // set by the registry: re-fetch this server's tools
+    protocolVersion; // what the server answered in the handshake (the /mcp panel shows it)
+    capabilities = []; // e.g. ["tools", "resources"] — the top-level keys the server declared
     constructor(def, token) {
         this.transport = makeTransport(def, token);
+        this.transport.onNotification = (method) => {
+            if (method === "notifications/tools/list_changed")
+                this.onToolsChanged?.();
+        };
     }
     request(method, params, timeoutMs) {
         return this.transport.request({ jsonrpc: "2.0", id: this.nextId++, method, params }, timeoutMs);
@@ -228,8 +313,17 @@ class McpClient {
         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.protocolVersion = init.result?.protocolVersion;
+        this.capabilities = Object.keys(init.result?.capabilities ?? {});
         this.transport.notify("notifications/initialized", {}); // tell the server we're ready
-        const list = await this.request("tools/list", {}, INIT_TIMEOUT_MS); // ask what it offers
+        // A server that promises tools/list_changed may change its tools later —
+        // open the channel it will announce that on (HTTP's event stream).
+        if (init.result?.capabilities?.tools?.listChanged)
+            this.transport.listen?.();
+        return this.listTools(); // ask what it offers
+    }
+    async listTools() {
+        const list = await this.request("tools/list", {}, INIT_TIMEOUT_MS);
         if (list.error)
             throw new Error(list.error.message);
         return list.result?.tools ?? [];
@@ -595,8 +689,10 @@ function markNeedsAuth(name, 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) {
+async function connectOne(name, retried = false, quiet = false) {
     const entry = entryFor(name);
+    const attempt = {}; // this connect's identity (see the guard after the handshake)
+    entry.attempt = attempt;
     // Unregister any stale tools from a previous connection.
     for (const n of entry.toolNames)
         unregisterExternalTool(n);
@@ -612,21 +708,31 @@ async function connectOne(name, retried = false) {
     }
     const client = new McpClient(entry.def, stored?.accessToken);
     try {
+        client.onToolsChanged = () => void refreshServerTools(name, client);
         const specs = await client.start(); // handshake + discover
+        // Connecting runs in the background now, so the world may have moved on
+        // while we waited: the user disabled it, reconnected it (a newer attempt),
+        // or a settings reload removed it. Then this result is stale — drop it.
+        if (registry.get(name) !== entry || entry.attempt !== attempt || entry.status === "disabled")
+            return client.kill();
         entry.client = client;
         entry.tools = registerTools(name, specs, client);
         entry.toolNames = specs.map((s) => `mcp__${name}__${s.name}`);
+        entry.toolSpecs = specs;
         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
+        if (!quiet)
+            console.log(chalk.dim(`(mcp: ${name} — ${specs.length} tools${entry.def.url ? " over http" : ""})`)); // visible on reconnect; a background startup stays silent (the status bar reports problems)
     }
     catch (err) {
         client.kill(); // don't leak the process/session
+        if (registry.get(name) !== entry || entry.attempt !== attempt || entry.status === "disabled")
+            return; // stale attempt — its failure no longer matters
         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);
+                return connectOne(name, true, quiet);
             markNeedsAuth(name, err);
         }
         else {
@@ -634,22 +740,167 @@ async function connectOne(name, retried = false) {
             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}`));
+        if (!quiet)
+            console.error(chalk.yellow(`  [mcp] ${name} ${entry.status === "needs-auth" ? `needs authentication (run /mcp auth ${name})` : "failed to start"}: ${err.message}`));
+    }
+}
+// The server said its tools changed (notifications/tools/list_changed): ask
+// again and swap the set in place — drop every mcp__<server>__ tool, register
+// the fresh ones, the same swap Claude Code does. The next model call sees the
+// new list (toolDefinitions() is rebuilt per call). A burst of notifications
+// coalesces: one refresh runs, and at most one more follows it.
+const refreshing = new Map();
+async function refreshServerTools(name, client) {
+    const running = refreshing.get(name);
+    if (running)
+        return void (running.again = true); // already fetching — fetch once more when done
+    const state = { again: false };
+    refreshing.set(name, state);
+    try {
+        do {
+            state.again = false;
+            const entry = registry.get(name);
+            if (!entry || entry.client !== client)
+                return; // reconnected, disabled or removed since — this client is stale
+            let specs;
+            try {
+                specs = await client.listTools();
+            }
+            catch {
+                return; // keep the tools we have; the next notification or a reconnect will retry
+            }
+            if (entry.client !== client)
+                return;
+            for (const n of entry.toolNames)
+                unregisterExternalTool(n);
+            entry.tools = registerTools(name, specs, client);
+            entry.toolNames = specs.map((s) => `mcp__${name}__${s.name}`);
+            entry.toolSpecs = specs;
+            emit("agent_mcp_tools_changed", { server: name, tools: specs.length });
+            console.log(chalk.dim(`(mcp: ${name} tools changed — ${specs.length} tools)`));
+        } while (state.again);
+    }
+    finally {
+        refreshing.delete(name);
     }
 }
 // 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() {
+//
+// Two modes. The interactive UI passes background: true — the Claude Code way:
+// every server is marked "pending" and connected in PARALLEL without blocking
+// startup; the prompt is usable at once, each server's tools appear the moment
+// it connects, and a failure shows up in the status bar instead of a log line.
+// Print mode (-p) and the readline REPL await everything first: a one-shot
+// task must see all its tools on the very first model call.
+export async function connectMcpServers(options = {}) {
     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
+    if (options.background) {
+        for (const name of entries)
+            entryFor(name).status = "pending";
+        for (const name of entries)
+            void connectOne(name, false, true); // fire and forget; connectOne never throws
+    }
+    else {
+        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
     };
 }
+// ---- hot reload: pick up settings.json edits without a restart ----------------
+// Adding a server used to mean quitting and relaunching. Now a settings change
+// is DIFFED against what is running and only the difference is touched:
+//   added   → connect it and register its tools
+//   removed → kill it and unregister its tools
+//   changed → reconnect it with the new definition
+//   same    → left alone (an unrelated settings edit reconnects nothing)
+// The tool list sent to the model is rebuilt every turn (toolDefinitions()), so
+// the next model call simply sees the new set. A tool call already in flight to
+// a server being removed fails with a readable error, like any dropped server.
+//
+// Claude Code swaps MCP tools the same way (drop every mcp__<server>__ tool,
+// append the fresh ones), but it only re-reads MCP config on explicit triggers
+// like /reload-plugins. We also watch the files, so a save is enough.
+// Key-order-independent JSON, so reformatting an entry doesn't count as a change.
+const stableJson = (v) => JSON.stringify(v, (_k, val) => (val && typeof val === "object" && !Array.isArray(val) ? Object.fromEntries(Object.entries(val).sort(([a], [b]) => a.localeCompare(b))) : val));
+// Reloads run one at a time: a second save while the first reload is still
+// connecting queues behind it instead of racing it over the same registry.
+let reloadChain = Promise.resolve();
+// Apply a new mcpServers map. `next` is the test seam; by default both settings
+// files are re-read. Returns one human-readable line per change ([] = nothing
+// changed), or a single warning line when the files can't be parsed right now.
+export function reloadMcpServers(next) {
+    const run = async () => {
+        const servers = next ?? readMcpServers();
+        if (!servers)
+            return ["settings.json is not valid JSON right now — MCP servers left unchanged"];
+        const previous = CONFIG.mcpServers;
+        CONFIG.mcpServers = servers; // entryFor / listMcpServers read the new map from here on
+        const changes = [];
+        for (const name of Object.keys(previous)) {
+            if (name in servers)
+                continue;
+            const entry = registry.get(name);
+            if (entry) {
+                for (const n of entry.toolNames)
+                    unregisterExternalTool(n);
+                entry.client?.kill();
+                registry.delete(name); // gone from the config → gone from /mcp too
+            }
+            changes.push(`removed ${name}`);
+        }
+        for (const [name, def] of Object.entries(servers)) {
+            const old = previous[name];
+            if (old && stableJson(old) === stableJson(def))
+                continue; // untouched
+            const entry = registry.get(name);
+            if (entry)
+                entry.def = def; // entryFor only builds new entries, so swap the def by hand
+            if (entry?.status === "disabled") {
+                changes.push(`updated ${name} (still disabled)`); // the user turned it off this session — respect that
+                continue;
+            }
+            await connectOne(name); // replaces any stale client + tools, logs its own status line
+            changes.push(`${old ? "reconnected" : "added"} ${name} (${registry.get(name)?.status})`);
+        }
+        return changes;
+    };
+    const result = reloadChain.then(run, run);
+    reloadChain = result.catch(() => { }); // a failed reload must not wedge the ones after it
+    return result;
+}
+// Watch both settings files and hot-reload on save. Polling (fs.watchFile), not
+// fs.watch: editors often save by writing a temp file and renaming it over the
+// original, which silently detaches an fs.watch handle; a stat poll just sees a
+// new mtime. It also works for a file that doesn't exist yet — create
+// .mini-agent/settings.json mid-session and it is picked up. Returns a stop function.
+const WATCH_INTERVAL_MS = 1000; // how often to stat; Claude Code polls ~/.claude.json at the same rate
+const RELOAD_DEBOUNCE_MS = 300; // a burst of writes (save + format-on-save) → one reload
+export function watchMcpConfig() {
+    let timer;
+    const onChange = (curr, prev) => {
+        if (curr.mtimeMs === prev.mtimeMs)
+            return; // a stat tick with nothing new
+        clearTimeout(timer);
+        timer = setTimeout(async () => {
+            const changes = await reloadMcpServers().catch((err) => [`reload failed: ${err.message}`]);
+            if (changes.length)
+                console.log(chalk.dim(`(mcp config changed: ${changes.join(", ")})`));
+        }, RELOAD_DEBOUNCE_MS);
+    };
+    const files = [GLOBAL_SETTINGS_PATH, PROJECT_SETTINGS_PATH];
+    for (const file of files)
+        fs.watchFile(file, { interval: WATCH_INTERVAL_MS, persistent: false }, onChange); // persistent:false — never keeps the process alive
+    return () => {
+        clearTimeout(timer);
+        for (const file of files)
+            fs.unwatchFile(file, onChange);
+    };
+}
 // ---- /mcp command support ----------------------------------------------------
 export function listMcpServers() {
     // Include every CONFIGURED server, even ones never attempted this session.
@@ -658,29 +909,70 @@ export function listMcpServers() {
         return {
             name,
             transport: def.url ? "http" : "stdio",
-            status: entry?.status ?? "failed",
+            status: entry?.status ?? "pending", // configured but not attempted yet (e.g. just added to settings)
             tools: entry?.tools ?? 0,
             error: entry?.error,
             authenticated: Boolean(oauthStore[name]?.accessToken),
             url: def.url,
+            command: def.command ? [def.command, ...(def.args ?? [])].join(" ") : undefined,
+            protocolVersion: entry?.status === "connected" ? entry.client?.protocolVersion : undefined,
+            capabilities: entry?.status === "connected" ? entry.client?.capabilities ?? [] : [],
+            toolSpecs: (entry?.toolSpecs ?? []).map((t) => ({ name: t.name, description: t.description })),
         };
     });
 }
-// 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.
+// /mcp <subcommand> <server> → the menu action it runs (scriptable, like Claude Code's /mcp).
+export const MCP_SUBCOMMANDS = { tools: "view-tools", auth: "authenticate", authenticate: "authenticate", "clear-auth": "clear-auth", reconnect: "reconnect", enable: "enable", disable: "disable" };
+// Which actions make sense for a server in a given state — Claude Code's menu,
+// in its order: View tools, (Re-)authenticate, Clear authentication,
+// Reconnect, Disable. A disabled server offers only Enable.
 export function mcpActionsFor(info) {
     if (info.status === "disabled") {
         return [{ label: "Enable", action: "enable" }];
     }
     const out = [];
+    if (info.status === "connected" && info.tools > 0)
+        out.push({ label: "View tools", action: "view-tools" });
     if (info.transport === "http") {
         out.push({ label: info.authenticated ? "Re-authenticate" : "Authenticate", action: "authenticate" });
+        if (info.authenticated)
+            out.push({ label: "Clear authentication", action: "clear-auth" });
     }
     out.push({ label: "Reconnect", action: "reconnect" });
     out.push({ label: "Disable", action: "disable" });
     return out;
 }
+// The server's details for the /mcp panel, one "Label: value" per line —
+// the same fields Claude Code's server screen shows.
+export function mcpServerDetails(info) {
+    const ok = (s) => chalk.green(`✔ ${s}`);
+    const status = { connected: ok("connected"), pending: chalk.dim("◌ connecting…"), "needs-auth": chalk.yellow("△ needs authentication"), failed: chalk.red("✗ failed"), disabled: chalk.dim("○ disabled") }[info.status];
+    const rows = [["Status", status + (info.status === "failed" && info.error ? chalk.dim(`  ${info.error}`) : "")]];
+    if (info.transport === "http")
+        rows.push(["Auth", info.authenticated ? ok("authenticated") : chalk.dim("not authenticated")]);
+    if (info.protocolVersion)
+        rows.push(["Protocol", chalk.dim(info.protocolVersion)]);
+    rows.push(info.url ? ["URL", chalk.dim(info.url)] : ["Command", chalk.dim(info.command ?? "")]);
+    rows.push(["Config location", chalk.dim(mcpConfigPath(info.name))]);
+    if (info.capabilities.length)
+        rows.push(["Capabilities", info.capabilities.join(" · ")]);
+    if (info.status === "connected")
+        rows.push(["Tools", chalk.dim(`${info.tools} tool${info.tools === 1 ? "" : "s"}`)]);
+    const width = Math.max(...rows.map(([k]) => k.length)) + 3;
+    return rows.map(([k, v]) => chalk.bold(`${k}:`.padEnd(width)) + v).join("\n");
+}
+// What the status bar should flag: servers that failed or need auth, and how
+// many are still connecting. Claude Code shows the same in its footer.
+// Only servers we actually tried count (the registry), so a session that never
+// connects MCP (tests, a front-end without it) shows nothing.
+export function mcpProblems() {
+    const live = [...registry.entries()].filter(([name]) => name in CONFIG.mcpServers);
+    return {
+        failed: live.filter(([, e]) => e.status === "failed").map(([name]) => name),
+        needsAuth: live.filter(([, e]) => e.status === "needs-auth").map(([name]) => name),
+        pending: live.filter(([, e]) => e.status === "pending").length,
+    };
+}
 // 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
@@ -744,6 +1036,26 @@ export async function authenticateMcpServer(name, onUrl) {
         ? `Authentication successful. Connected to ${name}.`
         : `Authentication done, but ${name} is ${status} — use /mcp reconnect ${name} to retry.`;
 }
+// Forget a server's stored OAuth tokens, then reconnect — without a token it
+// comes back as "needs auth" (or connected, if its config carries a static
+// header). The next /mcp auth starts a fresh browser flow.
+export async function clearMcpAuthentication(name) {
+    if (!CONFIG.mcpServers[name])
+        return `No MCP server named "${name}"`;
+    delete oauthStore[name];
+    writeOAuthStore(oauthStore);
+    await connectOne(name, false, true);
+    return `Cleared authentication for ${name}${entryFor(name).status === "needs-auth" ? ` — run /mcp auth ${name} to sign in again` : ""}.`;
+}
+// The tool list as text (name + the first line of its description).
+export function describeMcpTools(name) {
+    const info = listMcpServers().find((s) => s.name === name);
+    if (!info)
+        return `No MCP server named "${name}"`;
+    if (!info.toolSpecs.length)
+        return `${name} has no tools${info.status === "connected" ? "" : ` (${info.status})`}.`;
+    return [`${name} — ${info.toolSpecs.length} tool${info.toolSpecs.length === 1 ? "" : "s"}:`, ...info.toolSpecs.map((t) => `  ${chalk.bold(t.name)}${t.description ? chalk.dim(`  ${t.description.split("\n")[0].slice(0, 100)}`) : ""}`)].join("\n");
+}
 // 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) {
@@ -779,6 +1091,10 @@ export async function enableMcpServer(name) {
 // Run one action from mcpActionsFor and return the note to display.
 export async function runMcpAction(name, action, onUrl) {
     switch (action) {
+        case "view-tools":
+            return describeMcpTools(name);
+        case "clear-auth":
+            return clearMcpAuthentication(name);
         case "authenticate":
             return authenticateMcpServer(name, onUrl);
         case "reconnect":