@hasna/terminal 0.4.0 → 0.5.0

package/dist/App.js

@@ -12,6 +12,7 @@ import Browse from "./Browse.js";
 import FuzzyPicker from "./FuzzyPicker.js";
 import { createSession, logInteraction, updateInteraction } from "./sessions-db.js";
 import { smartDisplay } from "./smart-display.js";
+import { processOutput, shouldProcess } from "./output-processor.js";
 loadCache();
 const MAX_LINES = 20;
 // ── helpers ───────────────────────────────────────────────────────────────────
@@ -84,10 +85,20 @@ export default function App() {
         }));
     };
     const pushScroll = (entry) => updateTab(t => ({ ...t, scroll: [...t.scroll, { ...entry, expanded: false }] }));
-    const commitStream = (nl, cmd, lines, error) => {
+    const commitStream = async (nl, cmd, lines, error) => {
         const filePaths = !error ? extractFilePaths(lines) : [];
-        // Smart display: compress repetitive output (paths, duplicates, patterns)
-        const displayLines = !error && lines.length > 5 ? smartDisplay(lines) : lines;
+        // Smart display: first try pattern-based compression, then AI if still large
+        let displayLines = !error && lines.length > 5 ? smartDisplay(lines) : lines;
+        // AI-powered processing for large outputs (no hardcoded patterns)
+        if (!error && shouldProcess(lines.join("\n"))) {
+            try {
+                const processed = await processOutput(cmd, lines.join("\n"));
+                if (processed.aiProcessed && processed.tokensSaved > 50) {
+                    displayLines = processed.summary.split("\n");
+                }
+            }
+            catch { /* fallback to smartDisplay result */ }
+        }
         const truncated = displayLines.length > MAX_LINES;
         // Build short output summary for session context (first 10 lines of ORIGINAL output)
         const shortOutput = lines.slice(0, 10).join("\n") + (lines.length > 10 ? `\n... (${lines.length} lines total)` : "");
@@ -131,15 +142,16 @@ export default function App() {
                     }
                     catch { }
                 }
-                commitStream(nl, command, lines, code !== 0);
-                abortRef.current = null;
-                if (code !== 0 && !raw) {
-                    setPhase({ type: "autofix", nl, command, errorOutput: lines.join("\n") });
-                }
-                else {
-                    inputPhase({ raw });
-                }
-                resolve();
+                commitStream(nl, command, lines, code !== 0).then(() => {
+                    abortRef.current = null;
+                    if (code !== 0 && !raw) {
+                        setPhase({ type: "autofix", nl, command, errorOutput: lines.join("\n") });
+                    }
+                    else {
+                        inputPhase({ raw });
+                    }
+                    resolve();
+                });
             }, abort.signal);
         });
     };

package/dist/cli.js

@@ -167,6 +167,43 @@ else if (args[0] === "sessions") {
         }
     }
 }
+// ── Repo command ─────────────────────────────────────────────────────────────
+else if (args[0] === "repo") {
+    const { execSync } = await import("child_process");
+    const run = (cmd) => { try {
+        return execSync(cmd, { encoding: "utf8", cwd: process.cwd() }).trim();
+    }
+    catch {
+        return "";
+    } };
+    const branch = run("git branch --show-current");
+    const status = run("git status --short");
+    const log = run("git log --oneline -8 --decorate");
+    console.log(`Branch: ${branch}`);
+    if (status) {
+        console.log(`\nChanges:\n${status}`);
+    }
+    else {
+        console.log("\nClean working tree");
+    }
+    console.log(`\nRecent:\n${log}`);
+}
+// ── Symbols command ──────────────────────────────────────────────────────────
+else if (args[0] === "symbols" && args[1]) {
+    const { extractSymbolsFromFile } = await import("./search/semantic.js");
+    const { resolve } = await import("path");
+    const filePath = resolve(args[1]);
+    const symbols = extractSymbolsFromFile(filePath);
+    if (symbols.length === 0) {
+        console.log("No symbols found.");
+    }
+    else {
+        for (const s of symbols) {
+            const exp = s.exported ? "⬡" : "·";
+            console.log(`  ${exp} ${s.kind.padEnd(10)} L${String(s.line).padStart(4)}  ${s.name}`);
+        }
+    }
+}
 // ── Snapshot command ─────────────────────────────────────────────────────────
 else if (args[0] === "snapshot") {
     const { captureSnapshot } = await import("./snapshots.js");

package/dist/file-cache.js

@@ -0,0 +1,72 @@
+// Universal session file cache — cache any file read, serve from memory on repeat
+import { statSync, readFileSync } from "fs";
+const cache = new Map();
+/** Read a file with session caching. Returns content + cache metadata. */
+export function cachedRead(filePath, options = {}) {
+    const { offset, limit } = options;
+    try {
+        const stat = statSync(filePath);
+        const mtime = stat.mtimeMs;
+        const existing = cache.get(filePath);
+        // Cache hit — file unchanged
+        if (existing && existing.mtime === mtime) {
+            existing.readCount++;
+            existing.lastReadAt = Date.now();
+            const lines = existing.content.split("\n");
+            if (offset !== undefined || limit !== undefined) {
+                const start = offset ?? 0;
+                const end = limit !== undefined ? start + limit : lines.length;
+                return {
+                    content: lines.slice(start, end).join("\n"),
+                    cached: true,
+                    readCount: existing.readCount,
+                };
+            }
+            return { content: existing.content, cached: true, readCount: existing.readCount };
+        }
+        // Cache miss or stale — read from disk
+        const content = readFileSync(filePath, "utf8");
+        cache.set(filePath, {
+            content,
+            mtime,
+            readCount: 1,
+            firstReadAt: Date.now(),
+            lastReadAt: Date.now(),
+        });
+        const lines = content.split("\n");
+        if (offset !== undefined || limit !== undefined) {
+            const start = offset ?? 0;
+            const end = limit !== undefined ? start + limit : lines.length;
+            return { content: lines.slice(start, end).join("\n"), cached: false, readCount: 1 };
+        }
+        return { content, cached: false, readCount: 1 };
+    }
+    catch (e) {
+        return { content: `Error: ${e.message}`, cached: false, readCount: 0 };
+    }
+}
+/** Invalidate cache for a file (call after writes) */
+export function invalidateFile(filePath) {
+    cache.delete(filePath);
+}
+/** Invalidate all files matching a pattern */
+export function invalidatePattern(pattern) {
+    for (const key of cache.keys()) {
+        if (pattern.test(key))
+            cache.delete(key);
+    }
+}
+/** Get cache stats */
+export function cacheStats() {
+    let totalReads = 0;
+    let cacheHits = 0;
+    for (const entry of cache.values()) {
+        totalReads += entry.readCount;
+        cacheHits += Math.max(0, entry.readCount - 1); // first read is never cached
+    }
+    return { files: cache.size, totalReads, cacheHits };
+}
+/** Clear the entire cache */
+export function clearFileCache() {
+    cache.clear();
+}

package/dist/mcp/server.js

@@ -11,7 +11,9 @@ import { listRecipes, listCollections, getRecipe, createRecipe } from "../recipe
 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 { getEconomyStats, recordSaving } from "../economy.js";
 import { captureSnapshot } from "../snapshots.js";
 // ── helpers ──────────────────────────────────────────────────────────────────
@@ -110,6 +112,27 @@ export function createServer() {
         }
         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);
+        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,
+                    }) }],
+        };
+    });
     // ── 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)"),
@@ -354,6 +377,73 @@ export function createServer() {
         const sessions = listSessions(limit ?? 20);
         return { content: [{ type: "text", text: JSON.stringify(sessions) }] };
     });
+    // ── 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) }],
+        };
+    });
     return server;
 }
 // ── main: start MCP server via stdio ─────────────────────────────────────────

package/dist/output-processor.js

@@ -0,0 +1,95 @@
+// AI-powered output processor — uses cheap AI to intelligently summarize any output
+// NOTHING is hardcoded. The AI decides what's important, what's noise, what to keep.
+import { getProvider } from "./providers/index.js";
+import { estimateTokens } from "./parsers/index.js";
+import { recordSaving } from "./economy.js";
+const MIN_LINES_TO_PROCESS = 15;
+const MAX_OUTPUT_FOR_AI = 8000; // chars to send to AI (truncate if longer)
+const SUMMARIZE_PROMPT = `You are an output summarizer for a terminal. Given command output, return a CONCISE structured summary.
+
+RULES:
+- Return ONLY the summary, no explanations
+- For test output: show pass count, fail count, and ONLY the failing test names + errors
+- For build output: show status (ok/fail), error count, warning count
+- For install output: show package count, time, vulnerabilities
+- For file listings: show directory count, file count, notable files
+- For git output: show branch, status, key info
+- For logs: show line count, error count, latest error
+- For search results: show match count, top files
+- For ANY output: keep errors/failures/warnings, drop verbose/repetitive/progress lines
+- Use symbols: ✓ for success, ✗ for failure, ⚠ for warnings
+- Maximum 8 lines in your summary
+- If there are errors, ALWAYS include them verbatim`;
+/**
+ * Process command output through AI summarization.
+ * Cheap AI call (~100 tokens) saves 1000+ tokens downstream.
+ */
+export async function processOutput(command, output) {
+    const lines = output.split("\n");
+    // Short output — pass through, no AI needed
+    if (lines.length <= MIN_LINES_TO_PROCESS) {
+        return {
+            summary: output,
+            full: output,
+            tokensSaved: 0,
+            aiProcessed: false,
+        };
+    }
+    // Truncate very long output before sending to AI
+    let toSummarize = output;
+    if (toSummarize.length > MAX_OUTPUT_FOR_AI) {
+        const headChars = Math.floor(MAX_OUTPUT_FOR_AI * 0.6);
+        const tailChars = Math.floor(MAX_OUTPUT_FOR_AI * 0.3);
+        toSummarize = output.slice(0, headChars) +
+            `\n\n... (${lines.length} total lines, middle truncated) ...\n\n` +
+            output.slice(-tailChars);
+    }
+    try {
+        const provider = getProvider();
+        const summary = await provider.complete(`Command: ${command}\nOutput (${lines.length} lines):\n${toSummarize}`, {
+            system: SUMMARIZE_PROMPT,
+            maxTokens: 300,
+        });
+        const originalTokens = estimateTokens(output);
+        const summaryTokens = estimateTokens(summary);
+        const saved = Math.max(0, originalTokens - summaryTokens);
+        if (saved > 0) {
+            recordSaving("compressed", saved);
+        }
+        // Try to extract structured JSON if the AI returned it
+        let structured;
+        try {
+            const jsonMatch = summary.match(/\{[\s\S]*\}/);
+            if (jsonMatch) {
+                structured = JSON.parse(jsonMatch[0]);
+            }
+        }
+        catch { /* not JSON, that's fine */ }
+        return {
+            summary,
+            full: output,
+            structured,
+            tokensSaved: saved,
+            aiProcessed: true,
+        };
+    }
+    catch {
+        // AI unavailable — fall back to simple truncation
+        const head = lines.slice(0, 5).join("\n");
+        const tail = lines.slice(-5).join("\n");
+        const fallback = `${head}\n  ... (${lines.length - 10} lines hidden) ...\n${tail}`;
+        return {
+            summary: fallback,
+            full: output,
+            tokensSaved: Math.max(0, estimateTokens(output) - estimateTokens(fallback)),
+            aiProcessed: false,
+        };
+    }
+}
+/**
+ * Lightweight version — just decides IF output should be processed.
+ * Returns true if the output would benefit from AI summarization.
+ */
+export function shouldProcess(output) {
+    return output.split("\n").length > MIN_LINES_TO_PROCESS;
+}

package/dist/search/content-search.js

@@ -57,5 +57,12 @@ export async function searchContent(pattern, cwd, options = {}) {
     const result = { query: pattern, totalMatches, files, filtered };
     const resultTokens = Math.ceil(JSON.stringify(result).length / 4);
     result.tokensSaved = Math.max(0, rawTokens - resultTokens);
+    // Overflow guard — warn when results are truncated
+    if (totalMatches > maxResults * 3) {
+        result.overflow = {
+            warning: `${totalMatches} total matches across ${fileMap.size} files — showing top ${files.length}`,
+            suggestion: "Try a more specific pattern, add fileType filter, or use -l to list files only",
+        };
+    }
     return result;
 }

package/dist/search/semantic.js

@@ -13,6 +13,9 @@ function exec(command, cwd) {
     });
 }
 /** Extract code symbols from a TypeScript/JavaScript file using regex-based parsing */
+export function extractSymbolsFromFile(filePath) {
+    return extractSymbols(filePath);
+}
 function extractSymbols(filePath) {
     if (!existsSync(filePath))
         return [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hasna/terminal",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Smart terminal wrapper for AI agents and humans — structured output, token compression, MCP server, natural language",
   "type": "module",
   "bin": {

package/src/App.tsx

@@ -11,6 +11,7 @@ import Browse from "./Browse.js";
 import FuzzyPicker from "./FuzzyPicker.js";
 import { createSession, endSession, logInteraction, updateInteraction } from "./sessions-db.js";
 import { smartDisplay } from "./smart-display.js";
+import { processOutput, shouldProcess } from "./output-processor.js";
 
 loadCache();
 
@@ -134,10 +135,21 @@ export default function App() {
   const pushScroll = (entry: Omit<ScrollEntry, "expanded">) =>
     updateTab(t => ({ ...t, scroll: [...t.scroll, { ...entry, expanded: false }] }));
 
-  const commitStream = (nl: string, cmd: string, lines: string[], error: boolean) => {
+  const commitStream = async (nl: string, cmd: string, lines: string[], error: boolean) => {
     const filePaths = !error ? extractFilePaths(lines) : [];
-    // Smart display: compress repetitive output (paths, duplicates, patterns)
-    const displayLines = !error && lines.length > 5 ? smartDisplay(lines) : lines;
+    // Smart display: first try pattern-based compression, then AI if still large
+    let displayLines = !error && lines.length > 5 ? smartDisplay(lines) : lines;
+
+    // AI-powered processing for large outputs (no hardcoded patterns)
+    if (!error && shouldProcess(lines.join("\n"))) {
+      try {
+        const processed = await processOutput(cmd, lines.join("\n"));
+        if (processed.aiProcessed && processed.tokensSaved > 50) {
+          displayLines = processed.summary.split("\n");
+        }
+      } catch { /* fallback to smartDisplay result */ }
+    }
+
     const truncated = displayLines.length > MAX_LINES;
     // Build short output summary for session context (first 10 lines of ORIGINAL output)
     const shortOutput = lines.slice(0, 10).join("\n") + (lines.length > 10 ? `\n... (${lines.length} lines total)` : "");
@@ -185,14 +197,15 @@ export default function App() {
               updateTab(t => ({ ...t, cwd: newCwd }));
             } catch {}
           }
-          commitStream(nl, command, lines, code !== 0);
-          abortRef.current = null;
-          if (code !== 0 && !raw) {
-            setPhase({ type: "autofix", nl, command, errorOutput: lines.join("\n") });
-          } else {
-            inputPhase({ raw });
-          }
-          resolve();
+          commitStream(nl, command, lines, code !== 0).then(() => {
+            abortRef.current = null;
+            if (code !== 0 && !raw) {
+              setPhase({ type: "autofix", nl, command, errorOutput: lines.join("\n") });
+            } else {
+              inputPhase({ raw });
+            }
+            resolve();
+          });
         },
         abort.signal
       );

package/src/cli.tsx

@@ -152,6 +152,36 @@ else if (args[0] === "sessions") {
   }
 }
 
+// ── Repo command ─────────────────────────────────────────────────────────────
+
+else if (args[0] === "repo") {
+  const { execSync } = await import("child_process");
+  const run = (cmd: string) => { try { return execSync(cmd, { encoding: "utf8", cwd: process.cwd() }).trim(); } catch { return ""; } };
+  const branch = run("git branch --show-current");
+  const status = run("git status --short");
+  const log = run("git log --oneline -8 --decorate");
+  console.log(`Branch: ${branch}`);
+  if (status) { console.log(`\nChanges:\n${status}`); }
+  else { console.log("\nClean working tree"); }
+  console.log(`\nRecent:\n${log}`);
+}
+
+// ── Symbols command ──────────────────────────────────────────────────────────
+
+else if (args[0] === "symbols" && args[1]) {
+  const { extractSymbolsFromFile } = await import("./search/semantic.js");
+  const { resolve } = await import("path");
+  const filePath = resolve(args[1]);
+  const symbols = extractSymbolsFromFile(filePath);
+  if (symbols.length === 0) { console.log("No symbols found."); }
+  else {
+    for (const s of symbols) {
+      const exp = s.exported ? "⬡" : "·";
+      console.log(`  ${exp} ${s.kind.padEnd(10)} L${String(s.line).padStart(4)}  ${s.name}`);
+    }
+  }
+}
+
 // ── Snapshot command ─────────────────────────────────────────────────────────
 
 else if (args[0] === "snapshot") {

package/src/file-cache.ts

@@ -0,0 +1,95 @@
+// Universal session file cache — cache any file read, serve from memory on repeat
+
+import { statSync, readFileSync } from "fs";
+
+interface CachedFile {
+  content: string;
+  mtime: number;
+  readCount: number;
+  firstReadAt: number;
+  lastReadAt: number;
+}
+
+const cache = new Map<string, CachedFile>();
+
+/** Read a file with session caching. Returns content + cache metadata. */
+export function cachedRead(
+  filePath: string,
+  options: { offset?: number; limit?: number } = {}
+): { content: string; cached: boolean; readCount: number } {
+  const { offset, limit } = options;
+
+  try {
+    const stat = statSync(filePath);
+    const mtime = stat.mtimeMs;
+    const existing = cache.get(filePath);
+
+    // Cache hit — file unchanged
+    if (existing && existing.mtime === mtime) {
+      existing.readCount++;
+      existing.lastReadAt = Date.now();
+
+      const lines = existing.content.split("\n");
+      if (offset !== undefined || limit !== undefined) {
+        const start = offset ?? 0;
+        const end = limit !== undefined ? start + limit : lines.length;
+        return {
+          content: lines.slice(start, end).join("\n"),
+          cached: true,
+          readCount: existing.readCount,
+        };
+      }
+
+      return { content: existing.content, cached: true, readCount: existing.readCount };
+    }
+
+    // Cache miss or stale — read from disk
+    const content = readFileSync(filePath, "utf8");
+    cache.set(filePath, {
+      content,
+      mtime,
+      readCount: 1,
+      firstReadAt: Date.now(),
+      lastReadAt: Date.now(),
+    });
+
+    const lines = content.split("\n");
+    if (offset !== undefined || limit !== undefined) {
+      const start = offset ?? 0;
+      const end = limit !== undefined ? start + limit : lines.length;
+      return { content: lines.slice(start, end).join("\n"), cached: false, readCount: 1 };
+    }
+
+    return { content, cached: false, readCount: 1 };
+  } catch (e: any) {
+    return { content: `Error: ${e.message}`, cached: false, readCount: 0 };
+  }
+}
+
+/** Invalidate cache for a file (call after writes) */
+export function invalidateFile(filePath: string): void {
+  cache.delete(filePath);
+}
+
+/** Invalidate all files matching a pattern */
+export function invalidatePattern(pattern: RegExp): void {
+  for (const key of cache.keys()) {
+    if (pattern.test(key)) cache.delete(key);
+  }
+}
+
+/** Get cache stats */
+export function cacheStats(): { files: number; totalReads: number; cacheHits: number } {
+  let totalReads = 0;
+  let cacheHits = 0;
+  for (const entry of cache.values()) {
+    totalReads += entry.readCount;
+    cacheHits += Math.max(0, entry.readCount - 1); // first read is never cached
+  }
+  return { files: cache.size, totalReads, cacheHits };
+}
+
+/** Clear the entire cache */
+export function clearFileCache(): void {
+  cache.clear();
+}

package/src/mcp/server.ts

@@ -12,7 +12,9 @@ import { listRecipes, listCollections, getRecipe, createRecipe } from "../recipe
 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, cacheStats } from "../file-cache.js";
 import { getEconomyStats, recordSaving } from "../economy.js";
 import { captureSnapshot } from "../snapshots.js";
 
@@ -127,6 +129,35 @@ export function createServer(): McpServer {
     }
   );
 
+  // ── 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);
+
+      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,
+        }) }],
+      };
+    }
+  );
+
   // ── browse: list files/dirs as structured JSON ────────────────────────────
 
   server.tool(
@@ -509,6 +540,97 @@ export function createServer(): McpServer {
     }
   );
 
+  // ── 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" as const, 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: string[] = [];
+      const unstaged: string[] = [];
+      const untracked: string[] = [];
+      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" as const, 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" as const, text: JSON.stringify(fileSymbols) }],
+      };
+    }
+  );
+
   return server;
 }
 

package/src/output-processor.ts

@@ -0,0 +1,125 @@
+// AI-powered output processor — uses cheap AI to intelligently summarize any output
+// NOTHING is hardcoded. The AI decides what's important, what's noise, what to keep.
+
+import { getProvider } from "./providers/index.js";
+import { estimateTokens } from "./parsers/index.js";
+import { recordSaving } from "./economy.js";
+
+export interface ProcessedOutput {
+  /** AI-generated summary (concise, structured) */
+  summary: string;
+  /** Full original output (always available) */
+  full: string;
+  /** Structured JSON if the AI could extract it */
+  structured?: Record<string, unknown>;
+  /** How many tokens were saved */
+  tokensSaved: number;
+  /** Whether AI processing was used (vs passthrough) */
+  aiProcessed: boolean;
+}
+
+const MIN_LINES_TO_PROCESS = 15;
+const MAX_OUTPUT_FOR_AI = 8000; // chars to send to AI (truncate if longer)
+
+const SUMMARIZE_PROMPT = `You are an output summarizer for a terminal. Given command output, return a CONCISE structured summary.
+
+RULES:
+- Return ONLY the summary, no explanations
+- For test output: show pass count, fail count, and ONLY the failing test names + errors
+- For build output: show status (ok/fail), error count, warning count
+- For install output: show package count, time, vulnerabilities
+- For file listings: show directory count, file count, notable files
+- For git output: show branch, status, key info
+- For logs: show line count, error count, latest error
+- For search results: show match count, top files
+- For ANY output: keep errors/failures/warnings, drop verbose/repetitive/progress lines
+- Use symbols: ✓ for success, ✗ for failure, ⚠ for warnings
+- Maximum 8 lines in your summary
+- If there are errors, ALWAYS include them verbatim`;
+
+/**
+ * Process command output through AI summarization.
+ * Cheap AI call (~100 tokens) saves 1000+ tokens downstream.
+ */
+export async function processOutput(
+  command: string,
+  output: string,
+): Promise<ProcessedOutput> {
+  const lines = output.split("\n");
+
+  // Short output — pass through, no AI needed
+  if (lines.length <= MIN_LINES_TO_PROCESS) {
+    return {
+      summary: output,
+      full: output,
+      tokensSaved: 0,
+      aiProcessed: false,
+    };
+  }
+
+  // Truncate very long output before sending to AI
+  let toSummarize = output;
+  if (toSummarize.length > MAX_OUTPUT_FOR_AI) {
+    const headChars = Math.floor(MAX_OUTPUT_FOR_AI * 0.6);
+    const tailChars = Math.floor(MAX_OUTPUT_FOR_AI * 0.3);
+    toSummarize = output.slice(0, headChars) +
+      `\n\n... (${lines.length} total lines, middle truncated) ...\n\n` +
+      output.slice(-tailChars);
+  }
+
+  try {
+    const provider = getProvider();
+    const summary = await provider.complete(
+      `Command: ${command}\nOutput (${lines.length} lines):\n${toSummarize}`,
+      {
+        system: SUMMARIZE_PROMPT,
+        maxTokens: 300,
+      }
+    );
+
+    const originalTokens = estimateTokens(output);
+    const summaryTokens = estimateTokens(summary);
+    const saved = Math.max(0, originalTokens - summaryTokens);
+
+    if (saved > 0) {
+      recordSaving("compressed", saved);
+    }
+
+    // Try to extract structured JSON if the AI returned it
+    let structured: Record<string, unknown> | undefined;
+    try {
+      const jsonMatch = summary.match(/\{[\s\S]*\}/);
+      if (jsonMatch) {
+        structured = JSON.parse(jsonMatch[0]);
+      }
+    } catch { /* not JSON, that's fine */ }
+
+    return {
+      summary,
+      full: output,
+      structured,
+      tokensSaved: saved,
+      aiProcessed: true,
+    };
+  } catch {
+    // AI unavailable — fall back to simple truncation
+    const head = lines.slice(0, 5).join("\n");
+    const tail = lines.slice(-5).join("\n");
+    const fallback = `${head}\n  ... (${lines.length - 10} lines hidden) ...\n${tail}`;
+
+    return {
+      summary: fallback,
+      full: output,
+      tokensSaved: Math.max(0, estimateTokens(output) - estimateTokens(fallback)),
+      aiProcessed: false,
+    };
+  }
+}
+
+/**
+ * Lightweight version — just decides IF output should be processed.
+ * Returns true if the output would benefit from AI summarization.
+ */
+export function shouldProcess(output: string): boolean {
+  return output.split("\n").length > MIN_LINES_TO_PROCESS;
+}

package/src/search/content-search.ts

@@ -93,5 +93,13 @@ export async function searchContent(
   const resultTokens = Math.ceil(JSON.stringify(result).length / 4);
   result.tokensSaved = Math.max(0, rawTokens - resultTokens);
 
+  // Overflow guard — warn when results are truncated
+  if (totalMatches > maxResults * 3) {
+    (result as any).overflow = {
+      warning: `${totalMatches} total matches across ${fileMap.size} files — showing top ${files.length}`,
+      suggestion: "Try a more specific pattern, add fileType filter, or use -l to list files only",
+    };
+  }
+
   return result;
 }

package/src/search/semantic.ts

@@ -33,6 +33,10 @@ function exec(command: string, cwd: string): Promise<string> {
 }
 
 /** Extract code symbols from a TypeScript/JavaScript file using regex-based parsing */
+export function extractSymbolsFromFile(filePath: string): CodeSymbol[] {
+  return extractSymbols(filePath);
+}
+
 function extractSymbols(filePath: string): CodeSymbol[] {
   if (!existsSync(filePath)) return [];
   const content = readFileSync(filePath, "utf8");