@hasna/terminal 3.3.2 → 3.3.3

package/dist/mcp/server.js

@@ -60,7 +60,7 @@ export function createServer() {
         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).", {
+    server.tool("execute", "Run a shell command and return raw output. Prefer execute_smart for most tasks — it AI-summarizes output, saving 80% tokens. Use execute only when you need the full unprocessed output (e.g., to parse it yourself).", {
         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)"),
@@ -447,12 +447,24 @@ export function createServer() {
         };
     });
     // ── 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.", {
+    server.tool("read_file", "Read a file with session caching. Use summarize=true to get an AI-generated outline (~90% fewer tokens) instead of full content — ideal when you just want to understand what a file does without reading every line.", {
         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 }) => {
+        summarize: z.boolean().optional().describe("Return AI summary instead of full content (saves ~90% tokens)"),
+    }, async ({ path, offset, limit, summarize }) => {
         const result = cachedRead(path, { offset, limit });
+        if (summarize && result.content.length > 500) {
+            const processed = await processOutput(`cat ${path}`, result.content);
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            summary: processed.summary,
+                            lines: result.content.split("\n").length,
+                            tokensSaved: processed.tokensSaved,
+                            cached: result.cached,
+                        }) }],
+            };
+        }
         return {
             content: [{ type: "text", text: JSON.stringify({
                         content: result.content,

package/dist/output-processor.js

@@ -90,7 +90,10 @@ RULES:
 - Keep errors/failures verbatim
 - Be direct and concise — the user wants an ANSWER, not a data dump
 - For TEST OUTPUT: look for "X pass" and "X fail" lines. These are DEFINITIVE. If you see "42 pass, 0 fail" in the output, the answer is "42 tests pass, 0 fail." NEVER say "no tests found" or "incomplete" when pass/fail counts are visible.
-- For BUILD OUTPUT: if tsc/build exits 0 with no output, it SUCCEEDED. Empty output = success.`;
+- For BUILD OUTPUT: if tsc/build exits 0 with no output, it SUCCEEDED. Empty output = success.
+- For GREP/SEARCH OUTPUT (file:line:match format): List ALL matches grouped by file. NEVER summarize into one sentence. Format: "N matches in M files:" then list each match. The agent needs every match, not a prose interpretation.
+- For FILE LISTINGS (ls, find): show count + key entries. "23 files: src/ai.ts, src/cli.tsx, ..."
+- For GIT LOG/DIFF: preserve commit hashes, file names, and +/- line counts.`;
 /**
  * Process command output through AI summarization.
  * Cheap AI call (~100 tokens) saves 1000+ tokens downstream.

package/package.json

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

package/src/mcp/server.ts

@@ -69,7 +69,7 @@ export function createServer(): McpServer {
 
   server.tool(
     "execute",
-    "Run a shell command and return the result. Supports structured output parsing (json), token compression (compressed), and AI summarization (summary).",
+    "Run a shell command and return raw output. Prefer execute_smart for most tasks — it AI-summarizes output, saving 80% tokens. Use execute only when you need the full unprocessed output (e.g., to parse it yourself).",
     {
       command: z.string().describe("Shell command to execute"),
       cwd: z.string().optional().describe("Working directory (default: server cwd)"),
@@ -638,14 +638,28 @@ export function createServer(): McpServer {
 
   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.",
+    "Read a file with session caching. Use summarize=true to get an AI-generated outline (~90% fewer tokens) instead of full content — ideal when you just want to understand what a file does without reading every line.",
     {
       path: z.string().describe("File path"),
       offset: z.number().optional().describe("Start line (0-indexed)"),
       limit: z.number().optional().describe("Max lines to return"),
+      summarize: z.boolean().optional().describe("Return AI summary instead of full content (saves ~90% tokens)"),
     },
-    async ({ path, offset, limit }) => {
+    async ({ path, offset, limit, summarize }) => {
       const result = cachedRead(path, { offset, limit });
+
+      if (summarize && result.content.length > 500) {
+        const processed = await processOutput(`cat ${path}`, result.content);
+        return {
+          content: [{ type: "text" as const, text: JSON.stringify({
+            summary: processed.summary,
+            lines: result.content.split("\n").length,
+            tokensSaved: processed.tokensSaved,
+            cached: result.cached,
+          }) }],
+        };
+      }
+
       return {
         content: [{ type: "text" as const, text: JSON.stringify({
           content: result.content,

package/src/output-processor.ts

@@ -123,7 +123,10 @@ RULES:
 - Keep errors/failures verbatim
 - Be direct and concise — the user wants an ANSWER, not a data dump
 - For TEST OUTPUT: look for "X pass" and "X fail" lines. These are DEFINITIVE. If you see "42 pass, 0 fail" in the output, the answer is "42 tests pass, 0 fail." NEVER say "no tests found" or "incomplete" when pass/fail counts are visible.
-- For BUILD OUTPUT: if tsc/build exits 0 with no output, it SUCCEEDED. Empty output = success.`;
+- For BUILD OUTPUT: if tsc/build exits 0 with no output, it SUCCEEDED. Empty output = success.
+- For GREP/SEARCH OUTPUT (file:line:match format): List ALL matches grouped by file. NEVER summarize into one sentence. Format: "N matches in M files:" then list each match. The agent needs every match, not a prose interpretation.
+- For FILE LISTINGS (ls, find): show count + key entries. "23 files: src/ai.ts, src/cli.tsx, ..."
+- For GIT LOG/DIFF: preserve commit hashes, file names, and +/- line counts.`;
 
 /**
  * Process command output through AI summarization.