@hasna/terminal 4.2.0 → 4.3.1

package/src/mcp/tools/batch.ts

@@ -0,0 +1,106 @@
+// Batch tools: batch
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z, type ToolHelpers } from "./helpers.js";
+import { stripAnsi } from "../../compression.js";
+import { processOutput } from "../../output-processor.js";
+import { getOutputProvider } from "../../providers/index.js";
+import { searchContent } from "../../search/index.js";
+import { cachedRead } from "../../file-cache.js";
+
+export function registerBatchTools(server: McpServer, h: ToolHelpers): void {
+
+  server.tool(
+    "batch",
+    "Run multiple operations in ONE call. Saves N-1 round trips. Each op can be: execute (run command), read (file read/summarize), search (grep pattern), or symbols (file outline).",
+    {
+      ops: z.array(z.object({
+        type: z.enum(["execute", "read", "write", "search", "symbols"]).describe("Operation type"),
+        command: z.string().optional().describe("Shell command (for execute)"),
+        path: z.string().optional().describe("File path (for read/write/symbols)"),
+        content: z.string().optional().describe("File content (for write)"),
+        pattern: z.string().optional().describe("Search pattern (for search)"),
+        summarize: z.boolean().optional().describe("AI summarize (for read)"),
+        format: z.enum(["raw", "summary"]).optional().describe("Output format (for execute)"),
+      })).describe("Array of operations to run"),
+      cwd: z.string().optional().describe("Working directory for all ops"),
+    },
+    async ({ ops, cwd }) => {
+      const start = Date.now();
+      const workDir = cwd ?? process.cwd();
+      const results: Record<string, any>[] = [];
+
+      for (let i = 0; i < ops.slice(0, 10).length; i++) {
+        const op = ops[i];
+        try {
+          if (op.type === "execute" && op.command) {
+            const result = await h.exec(op.command, workDir, 30000);
+            const output = (result.stdout + result.stderr).trim();
+            if (op.format === "summary" && output.split("\n").length > 15) {
+              const processed = await processOutput(op.command, output);
+              results.push({ op: i, type: "execute", summary: processed.summary, exitCode: result.exitCode, tokensSaved: processed.tokensSaved });
+            } else {
+              results.push({ op: i, type: "execute", output: stripAnsi(output).slice(0, 2000), exitCode: result.exitCode });
+            }
+          } else if (op.type === "read" && op.path) {
+            const filePath = h.resolvePath(op.path, workDir);
+            const result = cachedRead(filePath, {});
+            if (op.summarize && result.content.length > 500) {
+              const provider = getOutputProvider();
+              const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+              const content = result.content.length > 8000 ? result.content.slice(0, 8000) : result.content;
+              const summary = await provider.complete(`File: ${filePath}\n\n${content}`, {
+                model: outputModel,
+                system: `Describe what this source file does in 2-4 lines. Include: main class/module name, key methods/functions, what it exports, and its purpose. Be specific.`,
+                maxTokens: 300, temperature: 0.2,
+              });
+              results.push({ op: i, type: "read", path: op.path, summary, lines: result.content.split("\n").length });
+            } else {
+              results.push({ op: i, type: "read", path: op.path, content: result.content, lines: result.content.split("\n").length });
+            }
+          } else if (op.type === "write" && op.path && op.content !== undefined) {
+            const filePath = h.resolvePath(op.path, workDir);
+            const { writeFileSync, mkdirSync, existsSync } = await import("fs");
+            const { dirname } = await import("path");
+            const dir = dirname(filePath);
+            if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+            writeFileSync(filePath, op.content);
+            results.push({ op: i, type: "write", path: op.path, ok: true, bytes: op.content.length });
+          } else if (op.type === "search" && op.pattern) {
+            // Search accepts both files and directories — resolve to parent dir if file
+            let searchPath = op.path ? h.resolvePath(op.path, workDir) : workDir;
+            try {
+              const { statSync } = await import("fs");
+              if (statSync(searchPath).isFile()) searchPath = searchPath.replace(/\/[^/]+$/, "");
+            } catch {}
+            const result = await searchContent(op.pattern, searchPath, {});
+            results.push({ op: i, type: "search", pattern: op.pattern, totalMatches: result.totalMatches, files: result.files.slice(0, 10) });
+          } else if (op.type === "symbols" && op.path) {
+            const filePath = h.resolvePath(op.path, workDir);
+            const result = cachedRead(filePath, {});
+            if (result.content && !result.content.startsWith("Error:")) {
+              const provider = getOutputProvider();
+              const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+              const content = result.content.length > 8000 ? result.content.slice(0, 8000) : result.content;
+              const summary = await provider.complete(`File: ${filePath}\n\n${content}`, {
+                model: outputModel,
+                system: `Extract all symbols. Return ONLY a JSON array. Each: {"name":"x","kind":"function|class|method|interface|type","line":N,"signature":"brief"}. For class methods use "Class.method". Exclude imports.`,
+                maxTokens: 2000, temperature: 0,
+              });
+              let symbols: any[] = [];
+              try { const m = summary.match(/\[[\s\S]*\]/); if (m) symbols = JSON.parse(m[0]); } catch {}
+              results.push({ op: i, type: "symbols", path: op.path, symbols });
+            } else {
+              results.push({ op: i, type: "symbols", path: op.path, error: "Cannot read file" });
+            }
+          }
+        } catch (err: any) {
+          results.push({ op: i, type: op.type, error: err.message?.slice(0, 200) });
+        }
+      }
+
+      h.logCall("batch", { command: `${ops.length} ops`, durationMs: Date.now() - start, aiProcessed: true });
+      return { content: [{ type: "text" as const, text: JSON.stringify({ results, total: results.length, durationMs: Date.now() - start }) }] };
+    }
+  );
+}

package/src/mcp/tools/execute.ts

@@ -0,0 +1,248 @@
+// Execute tools: execute, execute_smart, execute_diff, expand, browse, explain_error
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z, type ToolHelpers } from "./helpers.js";
+import { compress, stripAnsi } from "../../compression.js";
+import { estimateTokens } from "../../tokens.js";
+import { processOutput } from "../../output-processor.js";
+import { storeOutput, expandOutput } from "../../expand-store.js";
+import { shouldBeLazy, toLazy } from "../../lazy-executor.js";
+import { diffOutput } from "../../diff-cache.js";
+import { recordSaving } from "../../economy.js";
+
+export function registerExecuteTools(server: McpServer, h: ToolHelpers): void {
+
+  // ── execute: run a command, return structured result ──────────────────────
+
+  server.tool(
+    "execute",
+    "Run a shell command. Format guide: no format/raw for git commit/push (<50 tokens). format=compressed for long build output (CPU-only, no AI). format=json or format=summary for AI-summarized output (234ms, saves 80% tokens). Prefer execute_smart for most tasks.",
+    {
+      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 start = Date.now();
+      const result = await h.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);
+        if (shouldBeLazy(clean, command)) {
+          const lazy = toLazy(clean, command);
+          const detailKey = storeOutput(command, clean);
+          h.logCall("execute", { command, outputTokens: estimateTokens(clean), tokensSaved: 0, durationMs: Date.now() - start, exitCode: result.exitCode });
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({
+              exitCode: result.exitCode, ...lazy, detailKey, duration: result.duration,
+              ...(result.rewritten ? { rewrittenFrom: command } : {}),
+            }) }],
+          };
+        }
+        h.logCall("execute", { command, outputTokens: estimateTokens(clean), tokensSaved: 0, durationMs: Date.now() - start, exitCode: result.exitCode });
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({
+            exitCode: result.exitCode, output: clean, duration: result.duration, tokens: estimateTokens(clean),
+            ...(result.rewritten ? { rewrittenFrom: command } : {}),
+          }) }],
+        };
+      }
+
+      // JSON and Summary modes — both go through AI processing
+      if (format === "json" || format === "summary") {
+        try {
+          const processed = await processOutput(command, output);
+          const detailKey = output.split("\n").length > 15 ? storeOutput(command, output) : undefined;
+          h.logCall("execute", { command, outputTokens: estimateTokens(output), tokensSaved: processed.tokensSaved, durationMs: Date.now() - start, exitCode: result.exitCode, aiProcessed: processed.aiProcessed });
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({
+              exitCode: result.exitCode,
+              summary: processed.summary,
+              structured: processed.structured,
+              duration: result.duration,
+              tokensSaved: processed.tokensSaved,
+              aiProcessed: processed.aiProcessed,
+              ...(detailKey ? { detailKey, expandable: true } : {}),
+            }) }],
+          };
+        } catch {
+          const compressed = compress(command, output, { maxTokens });
+          h.logCall("execute", { command, outputTokens: estimateTokens(output), tokensSaved: compressed.tokensSaved, durationMs: Date.now() - start, exitCode: result.exitCode });
+          return {
+            content: [{ type: "text" as const, text: JSON.stringify({
+              exitCode: result.exitCode, output: compressed.content, duration: result.duration,
+              tokensSaved: compressed.tokensSaved,
+            }) }],
+          };
+        }
+      }
+
+      // Compressed mode — fast non-AI: strip + dedup + truncate
+      if (format === "compressed") {
+        const compressed = compress(command, output, { maxTokens });
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({
+            exitCode: result.exitCode, output: compressed.content, duration: result.duration,
+            ...(compressed.tokensSaved > 0 ? { tokensSaved: compressed.tokensSaved, savingsPercent: compressed.savingsPercent } : {}),
+          }) }],
+        };
+      }
+
+      return { content: [{ type: "text" as const, text: output }] };
+    }
+  );
+
+  // ── execute_smart: AI-powered output processing ────────────────────────────
+
+  server.tool(
+    "execute_smart",
+    "Run a command and get AI-summarized output (80-95% token savings). Use this for: test runs, builds, git operations, process management, system info. Do NOT use for file read/write — use your native Read/Write/Edit tools instead (they're faster, no shell overhead).",
+    {
+      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)"),
+      verbosity: z.enum(["minimal", "normal", "detailed"]).optional().describe("Summary detail level (default: normal)"),
+    },
+    async ({ command, cwd, timeout, verbosity }) => {
+      const start = Date.now();
+      const result = await h.exec(command, cwd, timeout ?? 30000, true);
+      const output = (result.stdout + result.stderr).trim();
+      const processed = await processOutput(command, output, undefined, verbosity);
+
+      const detailKey = output.split("\n").length > 15 ? storeOutput(command, output) : undefined;
+      h.logCall("execute_smart", { command, outputTokens: estimateTokens(output), tokensSaved: processed.tokensSaved, durationMs: Date.now() - start, exitCode: result.exitCode, aiProcessed: processed.aiProcessed });
+
+      return {
+        content: [{ type: "text" as const, 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 } : {}),
+        }) }],
+      };
+    }
+  );
+
+  // ── 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 start = Date.now();
+      const workDir = cwd ?? process.cwd();
+      const result = await h.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);
+      }
+      h.logCall("execute_diff", { command, outputTokens: estimateTokens(output), tokensSaved: diff.tokensSaved, durationMs: Date.now() - start, exitCode: result.exitCode });
+
+      if (diff.unchanged) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({
+          exitCode: result.exitCode, unchanged: true, diffSummary: diff.diffSummary,
+          duration: result.duration, tokensSaved: diff.tokensSaved,
+        }) }] };
+      }
+
+      if (diff.hasPrevious) {
+        return { content: [{ type: "text" as const, 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 (ANSI stripped)
+      const clean = stripAnsi(output);
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        exitCode: result.exitCode, output: clean,
+        diffSummary: "first run", duration: result.duration,
+      }) }] };
+    }
+  );
+
+  // ── 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" as const, text: JSON.stringify({ error: "Output expired or not found" }) }] };
+      }
+      return { content: [{ type: "text" as const, 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: string;
+      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 h.exec(command);
+      const files = result.stdout.split("\n").filter(l => l.trim());
+      return { content: [{ type: "text" as const, text: JSON.stringify({ cwd: target, files, count: files.length }) }] };
+    }
+  );
+
+  // ── 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 }) => {
+      // AI processes the error — no regex guessing
+      const processed = await processOutput(command ?? "unknown", error);
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify({
+          summary: processed.summary,
+          structured: processed.structured,
+          aiProcessed: processed.aiProcessed,
+        }) }],
+      };
+    }
+  );
+}