@hasna/terminal 2.3.1 → 2.3.2

package/dist/mcp/server.js

@@ -0,0 +1,569 @@
+// MCP Server for open-terminal — exposes terminal capabilities to AI agents
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { spawn } from "child_process";
+import { compress, stripAnsi } from "../compression.js";
+import { stripNoise } from "../noise-filter.js";
+import { parseOutput, tokenSavings, estimateTokens } from "../parsers/index.js";
+import { summarizeOutput } from "../ai.js";
+import { searchFiles, searchContent, semanticSearch } from "../search/index.js";
+import { listRecipes, listCollections, getRecipe, createRecipe } from "../recipes/storage.js";
+import { substituteVariables } from "../recipes/model.js";
+import { bgStart, bgStatus, bgStop, bgLogs, bgWaitPort } from "../supervisor.js";
+import { diffOutput } from "../diff-cache.js";
+import { processOutput } from "../output-processor.js";
+import { listSessions, getSessionInteractions, getSessionStats } from "../sessions-db.js";
+import { cachedRead } from "../file-cache.js";
+import { getBootContext } from "../session-boot.js";
+import { storeOutput, expandOutput } from "../expand-store.js";
+import { rewriteCommand } from "../command-rewriter.js";
+import { shouldBeLazy, toLazy } from "../lazy-executor.js";
+import { getEconomyStats, recordSaving } from "../economy.js";
+import { captureSnapshot } from "../snapshots.js";
+// ── helpers ──────────────────────────────────────────────────────────────────
+function exec(command, cwd, timeout) {
+    // Auto-optimize command before execution
+    const rw = rewriteCommand(command);
+    const actualCommand = rw.changed ? rw.rewritten : command;
+    return new Promise((resolve) => {
+        const start = Date.now();
+        const proc = spawn("/bin/zsh", ["-c", actualCommand], {
+            cwd: cwd ?? process.cwd(),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        proc.stdout?.on("data", (d) => { stdout += d.toString(); });
+        proc.stderr?.on("data", (d) => { stderr += d.toString(); });
+        const timer = timeout ? setTimeout(() => { try {
+            proc.kill("SIGTERM");
+        }
+        catch { } }, timeout) : null;
+        proc.on("close", (code) => {
+            if (timer)
+                clearTimeout(timer);
+            // Strip noise before returning (npm fund, progress bars, etc.)
+            const cleanStdout = stripNoise(stdout).cleaned;
+            const cleanStderr = stripNoise(stderr).cleaned;
+            resolve({ exitCode: code ?? 0, stdout: cleanStdout, stderr: cleanStderr, duration: Date.now() - start, rewritten: rw.changed ? rw.rewritten : undefined });
+        });
+    });
+}
+// ── server ───────────────────────────────────────────────────────────────────
+export function createServer() {
+    const server = new McpServer({
+        name: "open-terminal",
+        version: "0.2.0",
+    });
+    // ── execute: run a command, return structured result ──────────────────────
+    server.tool("execute", "Run a shell command and return the result. Supports structured output parsing (json), token compression (compressed), and AI summarization (summary).", {
+        command: z.string().describe("Shell command to execute"),
+        cwd: z.string().optional().describe("Working directory (default: server cwd)"),
+        timeout: z.number().optional().describe("Timeout in ms (default: 30000)"),
+        format: z.enum(["raw", "json", "compressed", "summary"]).optional().describe("Output format"),
+        maxTokens: z.number().optional().describe("Token budget for compressed/summary format"),
+    }, async ({ command, cwd, timeout, format, maxTokens }) => {
+        const result = await exec(command, cwd, timeout ?? 30000);
+        const output = (result.stdout + result.stderr).trim();
+        // Raw mode — with lazy execution for large results
+        if (!format || format === "raw") {
+            const clean = stripAnsi(output);
+            // Lazy mode: if >100 lines, return count + sample instead of full output
+            if (shouldBeLazy(clean, command)) {
+                const lazy = toLazy(clean, command);
+                const detailKey = storeOutput(command, clean);
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                exitCode: result.exitCode, ...lazy, detailKey, duration: result.duration,
+                                ...(result.rewritten ? { rewrittenFrom: command } : {}),
+                            }) }],
+                };
+            }
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            exitCode: result.exitCode, output: clean, duration: result.duration, tokens: estimateTokens(clean),
+                            ...(result.rewritten ? { rewrittenFrom: command } : {}),
+                        }) }],
+            };
+        }
+        // JSON mode — structured parsing (only if it actually saves tokens)
+        if (format === "json") {
+            const parsed = parseOutput(command, output);
+            if (parsed) {
+                const savings = tokenSavings(output, parsed.data);
+                if (savings.saved > 0) {
+                    return {
+                        content: [{ type: "text", text: JSON.stringify({
+                                    exitCode: result.exitCode, parsed: parsed.data, parser: parsed.parser,
+                                    duration: result.duration, tokensSaved: savings.saved, savingsPercent: savings.percent,
+                                }) }],
+                    };
+                }
+                // JSON was larger — fall through to compression
+            }
+        }
+        // Compressed mode (also fallback for json when no parser matches)
+        if (format === "compressed" || format === "json") {
+            const compressed = compress(command, output, { maxTokens, format: "json" });
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            exitCode: result.exitCode, output: compressed.content, format: compressed.format,
+                            duration: result.duration, tokensSaved: compressed.tokensSaved, savingsPercent: compressed.savingsPercent,
+                        }) }],
+            };
+        }
+        // Summary mode — AI-powered
+        if (format === "summary") {
+            try {
+                const summary = await summarizeOutput(command, output, maxTokens ?? 200);
+                const rawTokens = estimateTokens(output);
+                const summaryTokens = estimateTokens(summary);
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                exitCode: result.exitCode, summary, duration: result.duration,
+                                tokensSaved: rawTokens - summaryTokens,
+                            }) }],
+                };
+            }
+            catch {
+                const compressed = compress(command, output, { maxTokens });
+                return {
+                    content: [{ type: "text", text: JSON.stringify({
+                                exitCode: result.exitCode, output: compressed.content, duration: result.duration,
+                                tokensSaved: compressed.tokensSaved,
+                            }) }],
+                };
+            }
+        }
+        return { content: [{ type: "text", text: output }] };
+    });
+    // ── execute_smart: AI-powered output processing ────────────────────────────
+    server.tool("execute_smart", "Run a command and get AI-summarized output. The AI decides what's important — errors, failures, key results are kept; verbose logs, progress bars, passing tests are dropped. Saves 80-95% tokens vs raw output. Best tool for agents.", {
+        command: z.string().describe("Shell command to execute"),
+        cwd: z.string().optional().describe("Working directory"),
+        timeout: z.number().optional().describe("Timeout in ms (default: 30000)"),
+    }, async ({ command, cwd, timeout }) => {
+        const result = await exec(command, cwd, timeout ?? 30000);
+        const output = (result.stdout + result.stderr).trim();
+        const processed = await processOutput(command, output);
+        // Progressive disclosure: store full output, return summary + expand key
+        const detailKey = output.split("\n").length > 15 ? storeOutput(command, output) : undefined;
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        exitCode: result.exitCode,
+                        summary: processed.summary,
+                        structured: processed.structured,
+                        duration: result.duration,
+                        totalLines: output.split("\n").length,
+                        tokensSaved: processed.tokensSaved,
+                        aiProcessed: processed.aiProcessed,
+                        ...(detailKey ? { detailKey, expandable: true } : {}),
+                    }) }],
+        };
+    });
+    // ── expand: retrieve full output on demand ────────────────────────────────
+    server.tool("expand", "Retrieve full output from a previous execute_smart call. Only call this when you need details (e.g., to see failing test errors). Use the detailKey from execute_smart response.", {
+        key: z.string().describe("The detailKey from a previous execute_smart response"),
+        grep: z.string().optional().describe("Filter output lines by pattern (e.g., 'FAIL', 'error')"),
+    }, async ({ key, grep }) => {
+        const result = expandOutput(key, grep);
+        if (!result.found) {
+            return { content: [{ type: "text", text: JSON.stringify({ error: "Output expired or not found" }) }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify({ output: result.output, lines: result.lines }) }] };
+    });
+    // ── browse: list files/dirs as structured JSON ────────────────────────────
+    server.tool("browse", "List files and directories as structured JSON. Auto-filters node_modules, .git, dist by default.", {
+        path: z.string().optional().describe("Directory path (default: cwd)"),
+        recursive: z.boolean().optional().describe("List recursively (default: false)"),
+        maxDepth: z.number().optional().describe("Max depth for recursive listing (default: 2)"),
+        includeHidden: z.boolean().optional().describe("Include hidden files (default: false)"),
+    }, async ({ path, recursive, maxDepth, includeHidden }) => {
+        const target = path ?? process.cwd();
+        const depth = maxDepth ?? 2;
+        let command;
+        if (recursive) {
+            command = `find "${target}" -maxdepth ${depth} -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/.next/*'`;
+            if (!includeHidden)
+                command += " -not -name '.*'";
+        }
+        else {
+            command = includeHidden ? `ls -la "${target}"` : `ls -l "${target}"`;
+        }
+        const result = await exec(command);
+        const parsed = parseOutput(command, result.stdout);
+        if (parsed) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({ cwd: target, ...parsed.data, parser: parsed.parser }) }],
+            };
+        }
+        const files = result.stdout.split("\n").filter(l => l.trim());
+        return { content: [{ type: "text", text: JSON.stringify({ cwd: target, files }) }] };
+    });
+    // ── explain_error: structured error diagnosis ─────────────────────────────
+    server.tool("explain_error", "Parse error output and return structured diagnosis with root cause and fix suggestion.", {
+        error: z.string().describe("Error output text"),
+        command: z.string().optional().describe("The command that produced the error"),
+    }, async ({ error, command }) => {
+        const { errorParser } = await import("../parsers/errors.js");
+        if (errorParser.detect(command ?? "", error)) {
+            const info = errorParser.parse(command ?? "", error);
+            return { content: [{ type: "text", text: JSON.stringify(info) }] };
+        }
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        type: "unknown", message: error.split("\n")[0]?.trim() ?? "Unknown error",
+                    }) }],
+        };
+    });
+    // ── status: show server info ──────────────────────────────────────────────
+    server.tool("status", "Get open-terminal server status, capabilities, and available parsers.", async () => {
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        name: "open-terminal", version: "0.2.0", cwd: process.cwd(),
+                        parsers: ["ls", "find", "test", "git-log", "git-status", "build", "npm-install", "error"],
+                        features: ["structured-output", "token-compression", "ai-summary", "error-diagnosis"],
+                    }) }],
+        };
+    });
+    // ── search_files: smart file search with auto-filtering ────────────────────
+    server.tool("search_files", "Search for files by name pattern. Auto-filters node_modules, .git, dist. Returns categorized results (source, config, other) with token savings.", {
+        pattern: z.string().describe("Glob pattern (e.g., '*hooks*', '*.test.ts')"),
+        path: z.string().optional().describe("Search root (default: cwd)"),
+        includeNodeModules: z.boolean().optional().describe("Include node_modules (default: false)"),
+        maxResults: z.number().optional().describe("Max results per category (default: 50)"),
+    }, async ({ pattern, path, includeNodeModules, maxResults }) => {
+        const result = await searchFiles(pattern, path ?? process.cwd(), { includeNodeModules, maxResults });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    });
+    // ── search_content: smart grep with grouping ──────────────────────────────
+    server.tool("search_content", "Search file contents by regex pattern. Groups matches by file, sorted by relevance. Auto-filters excluded directories.", {
+        pattern: z.string().describe("Search pattern (regex)"),
+        path: z.string().optional().describe("Search root (default: cwd)"),
+        fileType: z.string().optional().describe("File type filter (e.g., 'ts', 'py')"),
+        maxResults: z.number().optional().describe("Max files to return (default: 30)"),
+        contextLines: z.number().optional().describe("Context lines around matches (default: 0)"),
+    }, async ({ pattern, path, fileType, maxResults, contextLines }) => {
+        const result = await searchContent(pattern, path ?? process.cwd(), { fileType, maxResults, contextLines });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    });
+    // ── search_semantic: AST-powered code search ───────────────────────────────
+    server.tool("search_semantic", "Semantic code search — find functions, classes, components, hooks, types by meaning. Uses AST parsing, not string matching. Much more precise than grep for code navigation.", {
+        query: z.string().describe("What to search for (e.g., 'auth functions', 'React components', 'database hooks')"),
+        path: z.string().optional().describe("Search root (default: cwd)"),
+        kinds: z.array(z.enum(["function", "class", "interface", "type", "variable", "export", "import", "component", "hook"])).optional().describe("Filter by symbol kind"),
+        exportedOnly: z.boolean().optional().describe("Only show exported symbols (default: false)"),
+        maxResults: z.number().optional().describe("Max results (default: 30)"),
+    }, async ({ query, path, kinds, exportedOnly, maxResults }) => {
+        const result = await semanticSearch(query, path ?? process.cwd(), {
+            kinds: kinds,
+            exportedOnly,
+            maxResults,
+        });
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    });
+    // ── list_recipes: list saved command recipes ──────────────────────────────
+    server.tool("list_recipes", "List saved command recipes. Optionally filter by collection or project.", {
+        collection: z.string().optional().describe("Filter by collection name"),
+        project: z.string().optional().describe("Project path for project-scoped recipes"),
+    }, async ({ collection, project }) => {
+        let recipes = listRecipes(project);
+        if (collection)
+            recipes = recipes.filter(r => r.collection === collection);
+        return { content: [{ type: "text", text: JSON.stringify(recipes) }] };
+    });
+    // ── run_recipe: execute a saved recipe ────────────────────────────────────
+    server.tool("run_recipe", "Run a saved recipe by name with optional variable substitution.", {
+        name: z.string().describe("Recipe name"),
+        variables: z.record(z.string(), z.string()).optional().describe("Variable values: {port: '3000'}"),
+        cwd: z.string().optional().describe("Working directory"),
+        format: z.enum(["raw", "json", "compressed"]).optional().describe("Output format"),
+    }, async ({ name, variables, cwd, format }) => {
+        const recipe = getRecipe(name, cwd);
+        if (!recipe) {
+            return { content: [{ type: "text", text: JSON.stringify({ error: `Recipe '${name}' not found` }) }] };
+        }
+        const command = variables ? substituteVariables(recipe.command, variables) : recipe.command;
+        const result = await exec(command, cwd, 30000);
+        const output = (result.stdout + result.stderr).trim();
+        if (format === "json") {
+            const parsed = parseOutput(command, output);
+            if (parsed) {
+                return { content: [{ type: "text", text: JSON.stringify({
+                                recipe: name, exitCode: result.exitCode, parsed: parsed.data, duration: result.duration,
+                            }) }] };
+            }
+        }
+        if (format === "compressed") {
+            const compressed = compress(command, output, { format: "json" });
+            return { content: [{ type: "text", text: JSON.stringify({
+                            recipe: name, exitCode: result.exitCode, output: compressed.content, duration: result.duration,
+                            tokensSaved: compressed.tokensSaved,
+                        }) }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify({
+                        recipe: name, exitCode: result.exitCode, output: stripAnsi(output), duration: result.duration,
+                    }) }] };
+    });
+    // ── save_recipe: save a new recipe ────────────────────────────────────────
+    server.tool("save_recipe", "Save a reusable command recipe. Variables in commands use {name} syntax.", {
+        name: z.string().describe("Recipe name"),
+        command: z.string().describe("Shell command (use {var} for variables)"),
+        description: z.string().optional().describe("Description"),
+        collection: z.string().optional().describe("Collection to add to"),
+        project: z.string().optional().describe("Project path (for project-scoped recipe)"),
+        tags: z.array(z.string()).optional().describe("Tags"),
+    }, async ({ name, command, description, collection, project, tags }) => {
+        const recipe = createRecipe({ name, command, description, collection, project, tags });
+        return { content: [{ type: "text", text: JSON.stringify(recipe) }] };
+    });
+    // ── list_collections: list recipe collections ─────────────────────────────
+    server.tool("list_collections", "List recipe collections.", {
+        project: z.string().optional().describe("Project path"),
+    }, async ({ project }) => {
+        const collections = listCollections(project);
+        return { content: [{ type: "text", text: JSON.stringify(collections) }] };
+    });
+    // ── bg_start: start a background process ───────────────────────────────────
+    server.tool("bg_start", "Start a background process (e.g., dev server). Auto-detects port from command.", {
+        command: z.string().describe("Command to run in background"),
+        cwd: z.string().optional().describe("Working directory"),
+    }, async ({ command, cwd }) => {
+        const result = bgStart(command, cwd);
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    });
+    // ── bg_status: list background processes ──────────────────────────────────
+    server.tool("bg_status", "List all managed background processes with status, ports, and recent output.", async () => {
+        return { content: [{ type: "text", text: JSON.stringify(bgStatus()) }] };
+    });
+    // ── bg_stop: stop a background process ────────────────────────────────────
+    server.tool("bg_stop", "Stop a managed background process by PID.", { pid: z.number().describe("Process ID to stop") }, async ({ pid }) => {
+        const ok = bgStop(pid);
+        return { content: [{ type: "text", text: JSON.stringify({ stopped: ok, pid }) }] };
+    });
+    // ── bg_logs: get process output ───────────────────────────────────────────
+    server.tool("bg_logs", "Get recent output lines from a background process.", {
+        pid: z.number().describe("Process ID"),
+        tail: z.number().optional().describe("Number of lines (default: 20)"),
+    }, async ({ pid, tail }) => {
+        const lines = bgLogs(pid, tail);
+        return { content: [{ type: "text", text: JSON.stringify({ pid, lines }) }] };
+    });
+    // ── bg_wait_port: wait for port to be ready ───────────────────────────────
+    server.tool("bg_wait_port", "Wait for a port to start accepting connections. Useful after starting a dev server.", {
+        port: z.number().describe("Port number to wait for"),
+        timeout: z.number().optional().describe("Timeout in ms (default: 30000)"),
+    }, async ({ port, timeout }) => {
+        const ready = await bgWaitPort(port, timeout);
+        return { content: [{ type: "text", text: JSON.stringify({ port, ready }) }] };
+    });
+    // ── execute_diff: run command with diff from last run ───────────────────────
+    server.tool("execute_diff", "Run a command and return diff from its last execution. Ideal for edit→test loops — only shows what changed.", {
+        command: z.string().describe("Shell command to execute"),
+        cwd: z.string().optional().describe("Working directory"),
+        timeout: z.number().optional().describe("Timeout in ms"),
+    }, async ({ command, cwd, timeout }) => {
+        const workDir = cwd ?? process.cwd();
+        const result = await exec(command, workDir, timeout ?? 30000);
+        const output = (result.stdout + result.stderr).trim();
+        const diff = diffOutput(command, workDir, output);
+        if (diff.tokensSaved > 0) {
+            recordSaving("diff", diff.tokensSaved);
+        }
+        if (diff.unchanged) {
+            return { content: [{ type: "text", text: JSON.stringify({
+                            exitCode: result.exitCode, unchanged: true, diffSummary: diff.diffSummary,
+                            duration: result.duration, tokensSaved: diff.tokensSaved,
+                        }) }] };
+        }
+        if (diff.hasPrevious) {
+            return { content: [{ type: "text", text: JSON.stringify({
+                            exitCode: result.exitCode, diffSummary: diff.diffSummary,
+                            added: diff.added.slice(0, 50), removed: diff.removed.slice(0, 50),
+                            duration: result.duration, tokensSaved: diff.tokensSaved,
+                        }) }] };
+        }
+        // First run — return full output
+        const compressed = compress(command, output, { format: "json" });
+        return { content: [{ type: "text", text: JSON.stringify({
+                        exitCode: result.exitCode, output: compressed.content,
+                        diffSummary: "first run", duration: result.duration,
+                    }) }] };
+    });
+    // ── token_stats: economy dashboard ────────────────────────────────────────
+    server.tool("token_stats", "Get token economy stats — how many tokens have been saved by structured output, compression, diffing, and caching.", async () => {
+        const stats = getEconomyStats();
+        return { content: [{ type: "text", text: JSON.stringify(stats) }] };
+    });
+    // ── snapshot: capture terminal state ──────────────────────────────────────
+    server.tool("snapshot", "Capture a compact snapshot of terminal state (cwd, env, running processes, recent commands, recipes). Useful for agent context handoff.", async () => {
+        const snap = captureSnapshot();
+        return { content: [{ type: "text", text: JSON.stringify(snap) }] };
+    });
+    // ── session_history: query session data ────────────────────────────────────
+    server.tool("session_history", "Query terminal session history — recent sessions, specific session details, or aggregate stats.", {
+        action: z.enum(["list", "detail", "stats"]).describe("list=recent sessions, detail=specific session, stats=aggregates"),
+        sessionId: z.string().optional().describe("Session ID (for detail action)"),
+        limit: z.number().optional().describe("Max sessions to return (for list, default: 20)"),
+    }, async ({ action, sessionId, limit }) => {
+        if (action === "stats") {
+            return { content: [{ type: "text", text: JSON.stringify(getSessionStats()) }] };
+        }
+        if (action === "detail" && sessionId) {
+            const interactions = getSessionInteractions(sessionId);
+            return { content: [{ type: "text", text: JSON.stringify(interactions) }] };
+        }
+        const sessions = listSessions(limit ?? 20);
+        return { content: [{ type: "text", text: JSON.stringify(sessions) }] };
+    });
+    // ── boot: session start context (replaces first 5 agent commands) ──────────
+    server.tool("boot", "Get everything an agent needs on session start in ONE call — git state, project info, source structure. Replaces: git status + git log + cat package.json + ls src/. Cached for the session.", async () => {
+        const ctx = await getBootContext(process.cwd());
+        return { content: [{ type: "text", text: JSON.stringify(ctx) }] };
+    });
+    // ── project_overview: orient agent in one call ─────────────────────────────
+    server.tool("project_overview", "Get project overview in one call — package.json info, source structure, config files. Replaces: cat package.json + ls src/ + cat tsconfig.json.", {
+        path: z.string().optional().describe("Project root (default: cwd)"),
+    }, async ({ path }) => {
+        const cwd = path ?? process.cwd();
+        const [pkgResult, srcResult, configResult] = await Promise.all([
+            exec("cat package.json 2>/dev/null", cwd),
+            exec("ls -1 src/ 2>/dev/null || ls -1 lib/ 2>/dev/null || ls -1 app/ 2>/dev/null", cwd),
+            exec("ls -1 *.json *.config.* .env* tsconfig* 2>/dev/null", cwd),
+        ]);
+        let pkg = null;
+        try {
+            pkg = JSON.parse(pkgResult.stdout);
+        }
+        catch { }
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        name: pkg?.name,
+                        version: pkg?.version,
+                        scripts: pkg?.scripts,
+                        dependencies: pkg?.dependencies ? Object.keys(pkg.dependencies) : [],
+                        devDependencies: pkg?.devDependencies ? Object.keys(pkg.devDependencies) : [],
+                        sourceFiles: srcResult.stdout.split("\n").filter(l => l.trim()),
+                        configFiles: configResult.stdout.split("\n").filter(l => l.trim()),
+                    }) }],
+        };
+    });
+    // ── last_commit: what just happened ───────────────────────────────────────
+    server.tool("last_commit", "Get details of the last commit — hash, message, files changed, diff stats. Replaces: git log -1 + git show --stat + git diff HEAD~1.", {
+        path: z.string().optional().describe("Repo path (default: cwd)"),
+    }, async ({ path }) => {
+        const cwd = path ?? process.cwd();
+        const [logResult, statResult] = await Promise.all([
+            exec("git log -1 --format='%H%n%s%n%an%n%ai'", cwd),
+            exec("git show --stat --format='' HEAD", cwd),
+        ]);
+        const [hash, message, author, date] = logResult.stdout.split("\n");
+        const filesChanged = statResult.stdout.split("\n").filter(l => l.trim() && !l.includes("changed"));
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        hash: hash?.trim(),
+                        message: message?.trim(),
+                        author: author?.trim(),
+                        date: date?.trim(),
+                        filesChanged,
+                    }) }],
+        };
+    });
+    // ── read_file: cached file reading ─────────────────────────────────────────
+    server.tool("read_file", "Read a file with session caching. Second read of unchanged file returns instantly from cache. Supports offset/limit for pagination without re-reading.", {
+        path: z.string().describe("File path"),
+        offset: z.number().optional().describe("Start line (0-indexed)"),
+        limit: z.number().optional().describe("Max lines to return"),
+    }, async ({ path, offset, limit }) => {
+        const result = cachedRead(path, { offset, limit });
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        content: result.content,
+                        cached: result.cached,
+                        readCount: result.readCount,
+                        ...(result.cached ? { note: `Served from cache (read #${result.readCount})` } : {}),
+                    }) }],
+        };
+    });
+    // ── repo_state: git status + diff + log in one call ───────────────────────
+    server.tool("repo_state", "Get full repository state in one call — branch, status, staged/unstaged files, recent commits. Replaces the common 3-command pattern: git status + git diff --stat + git log.", {
+        path: z.string().optional().describe("Repo path (default: cwd)"),
+    }, async ({ path }) => {
+        const cwd = path ?? process.cwd();
+        const [statusResult, diffResult, logResult] = await Promise.all([
+            exec("git status --porcelain", cwd),
+            exec("git diff --stat", cwd),
+            exec("git log --oneline -12 --decorate", cwd),
+        ]);
+        const branchResult = await exec("git branch --show-current", cwd);
+        const staged = [];
+        const unstaged = [];
+        const untracked = [];
+        for (const line of statusResult.stdout.split("\n").filter(l => l.trim())) {
+            const x = line[0], y = line[1], file = line.slice(3);
+            if (x === "?" && y === "?")
+                untracked.push(file);
+            else if (x !== " " && x !== "?")
+                staged.push(file);
+            if (y !== " " && y !== "?")
+                unstaged.push(file);
+        }
+        const commits = logResult.stdout.split("\n").filter(l => l.trim()).map(l => {
+            const match = l.match(/^([a-f0-9]+)\s+(.+)$/);
+            return match ? { hash: match[1], message: match[2] } : { hash: "", message: l };
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        branch: branchResult.stdout.trim(),
+                        dirty: staged.length + unstaged.length + untracked.length > 0,
+                        staged, unstaged, untracked,
+                        diffSummary: diffResult.stdout.trim() || "no changes",
+                        recentCommits: commits,
+                    }) }],
+        };
+    });
+    // ── symbols: file structure outline ───────────────────────────────────────
+    server.tool("symbols", "Get a structured outline of a source file — functions, classes, interfaces, exports with line numbers. Replaces the common grep pattern: grep -n '^export|class|function' file.", {
+        path: z.string().describe("File path to extract symbols from"),
+    }, async ({ path: filePath }) => {
+        const { semanticSearch } = await import("../search/semantic.js");
+        const dir = filePath.replace(/\/[^/]+$/, "") || ".";
+        const file = filePath.split("/").pop() ?? filePath;
+        const result = await semanticSearch(file.replace(/\.\w+$/, ""), dir, { maxResults: 50 });
+        // Filter to only symbols from the requested file
+        const fileSymbols = result.symbols.filter(s => s.file.endsWith(filePath) || s.file.endsWith("/" + filePath));
+        return {
+            content: [{ type: "text", text: JSON.stringify(fileSymbols) }],
+        };
+    });
+    // ── read_symbol: read a function/class by name ─────────────────────────────
+    server.tool("read_symbol", "Read a specific function, class, or interface by name from a source file. Returns only the code block — not the entire file. Saves 70-85% tokens vs reading the whole file.", {
+        path: z.string().describe("Source file path"),
+        name: z.string().describe("Symbol name (function, class, interface)"),
+    }, async ({ path: filePath, name }) => {
+        const { extractBlock, extractSymbolsFromFile } = await import("../search/semantic.js");
+        const block = extractBlock(filePath, name);
+        if (!block) {
+            // Return available symbols so the agent can pick the right one
+            const symbols = extractSymbolsFromFile(filePath);
+            const names = symbols.filter(s => s.kind !== "import").map(s => `${s.kind}: ${s.name} (L${s.line})`);
+            return { content: [{ type: "text", text: JSON.stringify({
+                            error: `Symbol '${name}' not found`,
+                            available: names.slice(0, 20),
+                        }) }] };
+        }
+        return { content: [{ type: "text", text: JSON.stringify({
+                        name, code: block.code, startLine: block.startLine, endLine: block.endLine,
+                        lines: block.endLine - block.startLine + 1,
+                    }) }] };
+    });
+    return server;
+}
+// ── main: start MCP server via stdio ─────────────────────────────────────────
+export async function startMcpServer() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("open-terminal MCP server running on stdio");
+}

package/dist/noise-filter.js

@@ -0,0 +1,86 @@
+// Noise filter — strips output that is NEVER useful for AI agents or humans
+// Applied before any parsing/compression so ALL features benefit
+const NOISE_PATTERNS = [
+    // npm noise
+    /^\d+ packages? are looking for funding/,
+    /^\s*run [`']?npm fund[`']? for details/,
+    /^found 0 vulnerabilities/,
+    /^npm warn deprecated\b/,
+    /^npm warn ERESOLVE\b/,
+    /^npm warn old lockfile/,
+    /^npm notice\b/,
+    // Progress bars and spinners
+    /[█▓▒░⣾⣽⣻⢿⡿⣟⣯⣷]{3,}/,
+    /\[\s*[=>#-]{5,}\s*\]\s*\d+%/, // [=====>    ] 45%
+    /^\s*[\\/|/-]{1}\s*$/, // spinner chars alone on a line
+    /Downloading\s.*\d+%/,
+    /Progress:\s*\d+%/i,
+    // Build noise
+    /^gyp info\b/,
+    /^gyp warn\b/,
+    /^TSFILE:/,
+    /^\s*hmr update\s/i,
+    // Python noise
+    /^Requirement already satisfied:/,
+    // Docker noise
+    /^Pulling fs layer/,
+    /^Waiting$/,
+    /^Downloading\s+\[/,
+    /^Extracting\s+\[/,
+    // Git LFS
+    /^Filtering content:/,
+    /^Git LFS:/,
+    // Generic download/upload progress
+    /^\s*\d+(\.\d+)?\s*[KMG]?B\s*\/\s*\d+(\.\d+)?\s*[KMG]?B\b/,
+];
+// Sensitive env var patterns — redact values, keep names only if needed
+const SENSITIVE_PATTERNS = [
+    /^(.*(?:KEY|TOKEN|SECRET|PASSWORD|CREDENTIAL|AUTH).*?)=(.+)$/i,
+    /^(.*(?:API_KEY|ACCESS_KEY|PRIVATE_KEY|CLIENT_SECRET).*?)=(.+)$/i,
+];
+/** Redact sensitive values in output (env vars, credentials) */
+function redactSensitive(line) {
+    for (const pattern of SENSITIVE_PATTERNS) {
+        const match = line.match(pattern);
+        if (match) {
+            return `${match[1]}=[REDACTED]`;
+        }
+    }
+    return line;
+}
+/** Strip noise lines from output. Returns cleaned output + count of lines removed. */
+export function stripNoise(output) {
+    const lines = output.split("\n");
+    let removed = 0;
+    const kept = [];
+    // Track consecutive blank lines
+    let blankRun = 0;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        // Collapse 3+ blank lines to 1
+        if (!trimmed) {
+            blankRun++;
+            if (blankRun <= 1)
+                kept.push(line);
+            else
+                removed++;
+            continue;
+        }
+        blankRun = 0;
+        // Check noise patterns
+        if (NOISE_PATTERNS.some(p => p.test(trimmed))) {
+            removed++;
+            continue;
+        }
+        // Carriage return overwrites (spinner animations)
+        if (line.includes("\r") && !line.endsWith("\r")) {
+            // Keep only the last part after \r
+            const parts = line.split("\r");
+            kept.push(parts[parts.length - 1]);
+            continue;
+        }
+        // Redact sensitive values (env vars with KEY, TOKEN, SECRET, etc.)
+        kept.push(redactSensitive(line));
+    }
+    return { cleaned: kept.join("\n"), linesRemoved: removed };
+}