@hasna/terminal 2.3.0 → 2.3.2

package/dist/discover.js

@@ -0,0 +1,212 @@
+// Discover — scan Claude Code session history to find token savings opportunities
+// Reads ~/.claude/projects/*/sessions/*.jsonl, extracts Bash commands + output sizes,
+// estimates how much terminal would have saved.
+import { readdirSync, readFileSync, statSync, existsSync } from "fs";
+import { join } from "path";
+import { estimateTokens } from "./parsers/index.js";
+/** Find all Claude session JSONL files */
+function findSessionFiles(claudeDir, maxAge) {
+    const files = [];
+    const projectsDir = join(claudeDir, "projects");
+    if (!existsSync(projectsDir))
+        return files;
+    const now = Date.now();
+    const cutoff = maxAge ? now - maxAge : 0;
+    try {
+        for (const project of readdirSync(projectsDir)) {
+            const projectPath = join(projectsDir, project);
+            // Look for session JSONL files (not subagents)
+            try {
+                for (const entry of readdirSync(projectPath)) {
+                    if (entry.endsWith(".jsonl")) {
+                        const filePath = join(projectPath, entry);
+                        try {
+                            const stat = statSync(filePath);
+                            if (stat.mtimeMs > cutoff)
+                                files.push(filePath);
+                        }
+                        catch { }
+                    }
+                }
+            }
+            catch { }
+        }
+    }
+    catch { }
+    return files;
+}
+/** Extract Bash commands and their output sizes from a session file */
+function extractCommands(sessionFile) {
+    const commands = [];
+    try {
+        const content = readFileSync(sessionFile, "utf8");
+        const lines = content.split("\n").filter(l => l.trim());
+        // Track tool_use IDs to match with tool_results
+        const pendingToolUses = new Map(); // id -> command
+        for (const line of lines) {
+            try {
+                const obj = JSON.parse(line);
+                const msg = obj.message;
+                if (!msg?.content || !Array.isArray(msg.content))
+                    continue;
+                for (const block of msg.content) {
+                    // Capture Bash tool_use commands
+                    if (block.type === "tool_use" && block.name === "Bash" && block.input?.command) {
+                        pendingToolUses.set(block.id, block.input.command);
+                    }
+                    // Capture tool_result outputs and match to commands
+                    if (block.type === "tool_result" && block.tool_use_id) {
+                        const command = pendingToolUses.get(block.tool_use_id);
+                        if (command) {
+                            let outputText = "";
+                            if (typeof block.content === "string") {
+                                outputText = block.content;
+                            }
+                            else if (Array.isArray(block.content)) {
+                                outputText = block.content
+                                    .filter((c) => c.type === "text")
+                                    .map((c) => c.text)
+                                    .join("\n");
+                            }
+                            if (outputText.length > 0) {
+                                commands.push({
+                                    command,
+                                    outputTokens: estimateTokens(outputText),
+                                    outputChars: outputText.length,
+                                    sessionFile,
+                                });
+                            }
+                            pendingToolUses.delete(block.tool_use_id);
+                        }
+                    }
+                }
+            }
+            catch { } // skip malformed lines
+        }
+    }
+    catch { } // skip unreadable files
+    return commands;
+}
+/** Categorize a command into a bucket */
+function categorizeCommand(cmd) {
+    const trimmed = cmd.trim();
+    if (/^git\b/.test(trimmed))
+        return "git";
+    if (/\b(bun|npm|yarn|pnpm)\s+(test|run\s+test)/.test(trimmed))
+        return "test";
+    if (/\b(bun|npm|yarn|pnpm)\s+run\s+(build|typecheck|lint)/.test(trimmed))
+        return "build";
+    if (/^(grep|rg)\b/.test(trimmed))
+        return "grep";
+    if (/^find\b/.test(trimmed))
+        return "find";
+    if (/^(cat|head|tail|less)\b/.test(trimmed))
+        return "read";
+    if (/^(ls|tree|du|wc)\b/.test(trimmed))
+        return "list";
+    if (/^(curl|wget|fetch)\b/.test(trimmed))
+        return "network";
+    if (/^(docker|kubectl|helm)\b/.test(trimmed))
+        return "infra";
+    if (/^(python|pip|pytest)\b/.test(trimmed))
+        return "python";
+    if (/^(cargo|rustc)\b/.test(trimmed))
+        return "rust";
+    if (/^(go\s|golangci)\b/.test(trimmed))
+        return "go";
+    return "other";
+}
+/** Normalize command for grouping (strip variable parts like paths, hashes) */
+function normalizeCommand(cmd) {
+    return cmd
+        .replace(/[0-9a-f]{7,40}/g, "{hash}") // git hashes
+        .replace(/\/[\w./-]+\.(ts|tsx|js|json|py|rs|go)\b/g, "{file}") // file paths
+        .replace(/\d{4}-\d{2}-\d{2}/g, "{date}") // dates
+        .replace(/:\d+/g, ":{line}") // line numbers
+        .trim();
+}
+/** Run discover across all Claude sessions */
+export function discover(options = {}) {
+    const claudeDir = join(process.env.HOME ?? "~", ".claude");
+    const maxAge = (options.maxAgeDays ?? 30) * 24 * 60 * 60 * 1000;
+    const minTokens = options.minTokens ?? 50;
+    const sessionFiles = findSessionFiles(claudeDir, maxAge);
+    const allCommands = [];
+    for (const file of sessionFiles) {
+        allCommands.push(...extractCommands(file));
+    }
+    // Filter to commands with meaningful output
+    const significant = allCommands.filter(c => c.outputTokens >= minTokens);
+    // Group by normalized command
+    const groups = new Map();
+    for (const cmd of significant) {
+        const key = normalizeCommand(cmd.command);
+        const existing = groups.get(key) ?? { count: 0, totalTokens: 0, example: cmd.command };
+        existing.count++;
+        existing.totalTokens += cmd.outputTokens;
+        groups.set(key, existing);
+    }
+    // Top commands by total tokens
+    const topCommands = [...groups.entries()]
+        .map(([cmd, data]) => ({
+        command: data.example,
+        count: data.count,
+        totalTokens: data.totalTokens,
+        avgTokens: Math.round(data.totalTokens / data.count),
+    }))
+        .sort((a, b) => b.totalTokens - a.totalTokens)
+        .slice(0, 20);
+    // Category breakdown
+    const commandsByCategory = {};
+    for (const cmd of significant) {
+        const cat = categorizeCommand(cmd.command);
+        if (!commandsByCategory[cat])
+            commandsByCategory[cat] = { count: 0, tokens: 0 };
+        commandsByCategory[cat].count++;
+        commandsByCategory[cat].tokens += cmd.outputTokens;
+    }
+    const totalOutputTokens = significant.reduce((sum, c) => sum + c.outputTokens, 0);
+    // Conservative 70% compression estimate (RTK claims 60-90%)
+    const estimatedSavings = Math.round(totalOutputTokens * 0.7);
+    // Each saved input token is repeated across ~5 turns on average before compaction
+    const multipliedSavings = estimatedSavings * 5;
+    // At Opus rates ($5/M input tokens)
+    const estimatedSavingsUsd = (multipliedSavings * 5) / 1_000_000;
+    return {
+        totalSessions: sessionFiles.length,
+        totalCommands: significant.length,
+        totalOutputTokens,
+        estimatedSavings,
+        estimatedSavingsUsd,
+        topCommands,
+        commandsByCategory,
+    };
+}
+/** Format discover report for CLI display */
+export function formatDiscoverReport(report) {
+    const lines = [];
+    lines.push(`📊 Terminal Discover — Token Savings Analysis`);
+    lines.push(`   Scanned ${report.totalSessions} sessions, ${report.totalCommands} commands with >50 token output\n`);
+    lines.push(`💰 Estimated savings with open-terminal:`);
+    lines.push(`   Output tokens: ${report.totalOutputTokens.toLocaleString()}`);
+    lines.push(`   Compressible:  ${report.estimatedSavings.toLocaleString()} tokens (70% avg)`);
+    lines.push(`   Repeated ~5x before compaction = ${(report.estimatedSavings * 5).toLocaleString()} billable tokens`);
+    lines.push(`   At Opus rates: $${report.estimatedSavingsUsd.toFixed(2)} saved\n`);
+    if (report.topCommands.length > 0) {
+        lines.push(`🔝 Top commands by token cost:`);
+        for (const cmd of report.topCommands.slice(0, 15)) {
+            const avg = cmd.avgTokens.toLocaleString().padStart(6);
+            const total = cmd.totalTokens.toLocaleString().padStart(8);
+            lines.push(`   ${String(cmd.count).padStart(4)}× ${avg} avg → ${total} total  ${cmd.command.slice(0, 60)}`);
+        }
+        lines.push("");
+    }
+    if (Object.keys(report.commandsByCategory).length > 0) {
+        lines.push(`📁 By category:`);
+        const sorted = Object.entries(report.commandsByCategory).sort((a, b) => b[1].tokens - a[1].tokens);
+        for (const [cat, data] of sorted) {
+            lines.push(`   ${cat.padEnd(10)} ${String(data.count).padStart(5)} cmds  ${data.tokens.toLocaleString().padStart(10)} tokens`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/economy.js

@@ -0,0 +1,123 @@
+// Token economy tracker — tracks token savings across all interactions
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const DIR = join(homedir(), ".terminal");
+const ECONOMY_FILE = join(DIR, "economy.json");
+let stats = null;
+function ensureDir() {
+    if (!existsSync(DIR))
+        mkdirSync(DIR, { recursive: true });
+}
+function loadStats() {
+    if (stats)
+        return stats;
+    ensureDir();
+    if (existsSync(ECONOMY_FILE)) {
+        try {
+            const saved = JSON.parse(readFileSync(ECONOMY_FILE, "utf8"));
+            stats = {
+                totalTokensSaved: saved.totalTokensSaved ?? 0,
+                totalTokensUsed: saved.totalTokensUsed ?? 0,
+                savingsByFeature: {
+                    structured: saved.savingsByFeature?.structured ?? 0,
+                    compressed: saved.savingsByFeature?.compressed ?? 0,
+                    diff: saved.savingsByFeature?.diff ?? 0,
+                    cache: saved.savingsByFeature?.cache ?? 0,
+                    search: saved.savingsByFeature?.search ?? 0,
+                },
+                sessionStart: Date.now(),
+                sessionSaved: 0,
+                sessionUsed: 0,
+            };
+            return stats;
+        }
+        catch { }
+    }
+    stats = {
+        totalTokensSaved: 0,
+        totalTokensUsed: 0,
+        savingsByFeature: { structured: 0, compressed: 0, diff: 0, cache: 0, search: 0 },
+        sessionStart: Date.now(),
+        sessionSaved: 0,
+        sessionUsed: 0,
+    };
+    return stats;
+}
+function saveStats() {
+    ensureDir();
+    if (stats) {
+        writeFileSync(ECONOMY_FILE, JSON.stringify(stats, null, 2));
+    }
+}
+/** Record token savings from a feature */
+export function recordSaving(feature, tokensSaved) {
+    const s = loadStats();
+    s.totalTokensSaved += tokensSaved;
+    s.sessionSaved += tokensSaved;
+    s.savingsByFeature[feature] += tokensSaved;
+    saveStats();
+}
+/** Record tokens used (for AI calls) */
+export function recordUsage(tokens) {
+    const s = loadStats();
+    s.totalTokensUsed += tokens;
+    s.sessionUsed += tokens;
+    saveStats();
+}
+/** Get current economy stats */
+export function getEconomyStats() {
+    return { ...loadStats() };
+}
+/** Format token count for display */
+export function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return `${n}`;
+}
+// ── Weighted economics ──────────────────────────────────────────────────────
+// Saved input tokens are repeated across multiple turns before compaction.
+// Weighted pricing accounts for the actual billing impact.
+/** Provider pricing per million tokens */
+const PROVIDER_PRICING = {
+    cerebras: { input: 0.60, output: 1.20 },
+    groq: { input: 0.15, output: 0.60 },
+    xai: { input: 0.20, output: 1.50 },
+    anthropic: { input: 0.80, output: 4.00 }, // Haiku
+    "anthropic-sonnet": { input: 3.00, output: 15.00 },
+    "anthropic-opus": { input: 5.00, output: 25.00 },
+};
+/** Estimate USD savings from compressed tokens */
+export function estimateSavingsUsd(tokensSaved, consumerModel = "anthropic-opus", avgTurnsBeforeCompaction = 5) {
+    const pricing = PROVIDER_PRICING[consumerModel] ?? PROVIDER_PRICING["anthropic-opus"];
+    const multipliedTokens = tokensSaved * avgTurnsBeforeCompaction;
+    const savingsUsd = (multipliedTokens * pricing.input) / 1_000_000;
+    return { savingsUsd, multipliedTokens, ratePerMillion: pricing.input };
+}
+/** Format a full economics summary */
+export function formatEconomicsSummary() {
+    const s = loadStats();
+    const opus = estimateSavingsUsd(s.totalTokensSaved, "anthropic-opus");
+    const sonnet = estimateSavingsUsd(s.totalTokensSaved, "anthropic-sonnet");
+    const haiku = estimateSavingsUsd(s.totalTokensSaved, "anthropic");
+    return [
+        `Token Economy:`,
+        `  Tokens saved:  ${formatTokens(s.totalTokensSaved)}`,
+        `  Tokens used:   ${formatTokens(s.totalTokensUsed)}`,
+        `  Ratio:         ${s.totalTokensUsed > 0 ? (s.totalTokensSaved / s.totalTokensUsed).toFixed(1) : "∞"}x return`,
+        ``,
+        `  Estimated USD savings (×5 turns before compaction):`,
+        `    Opus ($5/M):   $${opus.savingsUsd.toFixed(2)} (${formatTokens(opus.multipliedTokens)} billable tokens)`,
+        `    Sonnet ($3/M): $${sonnet.savingsUsd.toFixed(2)}`,
+        `    Haiku ($0.8/M): $${haiku.savingsUsd.toFixed(2)}`,
+        ``,
+        `  By feature:`,
+        `    Compressed: ${formatTokens(s.savingsByFeature.compressed)}`,
+        `    Structured: ${formatTokens(s.savingsByFeature.structured)}`,
+        `    Diff cache: ${formatTokens(s.savingsByFeature.diff)}`,
+        `    NL cache:   ${formatTokens(s.savingsByFeature.cache)}`,
+        `    Search:     ${formatTokens(s.savingsByFeature.search)}`,
+    ].join("\n");
+}

package/dist/expand-store.js

@@ -0,0 +1,38 @@
+// Expand store — keeps full output for progressive disclosure
+// Agents get summary first, call expand(key) only if they need details
+const MAX_ENTRIES = 50;
+const store = new Map();
+let counter = 0;
+/** Store full output and return a retrieval key */
+export function storeOutput(command, output) {
+    const key = `out_${++counter}`;
+    // Evict oldest if over limit
+    if (store.size >= MAX_ENTRIES) {
+        const oldest = store.keys().next().value;
+        if (oldest)
+            store.delete(oldest);
+    }
+    store.set(key, { command, output, timestamp: Date.now() });
+    return key;
+}
+/** Retrieve full output by key, optionally filtered */
+export function expandOutput(key, grep) {
+    const entry = store.get(key);
+    if (!entry)
+        return { found: false };
+    let output = entry.output;
+    if (grep) {
+        const pattern = new RegExp(grep, "i");
+        output = output.split("\n").filter(l => pattern.test(l)).join("\n");
+    }
+    return { found: true, output, lines: output.split("\n").length };
+}
+/** List available stored outputs */
+export function listStored() {
+    return [...store.entries()].map(([key, entry]) => ({
+        key,
+        command: entry.command.slice(0, 60),
+        lines: entry.output.split("\n").length,
+        age: Date.now() - entry.timestamp,
+    }));
+}

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/file-index.js

@@ -0,0 +1,62 @@
+// Pre-computed file index — build once, serve search from memory
+// Eliminates subprocess spawning for repeat file queries
+import { spawn } from "child_process";
+let index = null;
+let indexCwd = "";
+let indexTime = 0;
+let watcher = null;
+const INDEX_TTL = 30_000; // 30 seconds
+function exec(command, cwd) {
+    return new Promise((resolve) => {
+        const proc = spawn("/bin/zsh", ["-c", command], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        let out = "";
+        proc.stdout?.on("data", (d) => { out += d.toString(); });
+        proc.on("close", () => resolve(out));
+    });
+}
+/** Build or return cached file index */
+export async function getFileIndex(cwd) {
+    // Return cached if fresh
+    if (index && indexCwd === cwd && Date.now() - indexTime < INDEX_TTL) {
+        return index;
+    }
+    const raw = await exec("find . -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' -not -path '*/.next/*' -not -path '*/build/*' 2>/dev/null", cwd);
+    index = raw.split("\n").filter(l => l.trim()).map(p => {
+        const path = p.trim();
+        const parts = path.split("/");
+        const name = parts[parts.length - 1] ?? path;
+        const dir = parts.slice(0, -1).join("/") || ".";
+        const ext = name.includes(".") ? "." + name.split(".").pop() : "";
+        return { path, dir, name, ext };
+    });
+    indexCwd = cwd;
+    indexTime = Date.now();
+    return index;
+}
+/** Search file index by glob pattern (in-memory, no subprocess) */
+export async function searchIndex(cwd, pattern) {
+    const idx = await getFileIndex(cwd);
+    // Convert glob to regex
+    const regex = new RegExp("^" + pattern
+        .replace(/\./g, "\\.")
+        .replace(/\*/g, ".*")
+        .replace(/\?/g, ".")
+        + "$", "i");
+    return idx.filter(e => regex.test(e.name) || regex.test(e.path)).map(e => e.path);
+}
+/** Get file index stats */
+export async function indexStats(cwd) {
+    const idx = await getFileIndex(cwd);
+    const byExt = {};
+    const byDir = {};
+    for (const e of idx) {
+        byExt[e.ext || "(none)"] = (byExt[e.ext || "(none)"] ?? 0) + 1;
+        const topDir = e.dir.split("/").slice(0, 2).join("/");
+        byDir[topDir] = (byDir[topDir] ?? 0) + 1;
+    }
+    return { totalFiles: idx.length, byExtension: byExt, byDir };
+}
+/** Invalidate index */
+export function invalidateIndex() {
+    index = null;
+}

package/dist/history.js

@@ -0,0 +1,62 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const DIR = join(homedir(), ".terminal");
+const HISTORY_FILE = join(DIR, "history.json");
+const CONFIG_FILE = join(DIR, "config.json");
+export const DEFAULT_PERMISSIONS = {
+    destructive: true,
+    network: true,
+    sudo: true,
+    write_outside_cwd: true,
+    install: true,
+};
+export const DEFAULT_CONFIG = {
+    onboarded: false,
+    confirm: false,
+    permissions: DEFAULT_PERMISSIONS,
+};
+function ensureDir() {
+    if (!existsSync(DIR))
+        mkdirSync(DIR, { recursive: true });
+}
+export function loadHistory() {
+    ensureDir();
+    if (!existsSync(HISTORY_FILE))
+        return [];
+    try {
+        return JSON.parse(readFileSync(HISTORY_FILE, "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+export function saveHistory(entries) {
+    ensureDir();
+    writeFileSync(HISTORY_FILE, JSON.stringify(entries.slice(-500), null, 2));
+}
+export function appendHistory(entry) {
+    const existing = loadHistory();
+    saveHistory([...existing, entry]);
+}
+export function loadConfig() {
+    ensureDir();
+    if (!existsSync(CONFIG_FILE))
+        return { ...DEFAULT_CONFIG };
+    try {
+        const saved = JSON.parse(readFileSync(CONFIG_FILE, "utf8"));
+        return {
+            ...DEFAULT_CONFIG,
+            ...saved,
+            confirm: saved.confirm ?? false,
+            permissions: { ...DEFAULT_PERMISSIONS, ...(saved.permissions ?? {}) },
+        };
+    }
+    catch {
+        return { ...DEFAULT_CONFIG };
+    }
+}
+export function saveConfig(config) {
+    ensureDir();
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+}

package/dist/lazy-executor.js

@@ -0,0 +1,54 @@
+// Lazy execution — for large result sets, return count + sample + categories
+// instead of full output. Agent requests slices on demand.
+import { dirname } from "path";
+const LAZY_THRESHOLD = 200; // lines before switching to lazy mode (was 100, too aggressive)
+// Commands where the user explicitly wants full output — never lazify
+const PASSTHROUGH_COMMANDS = [
+    // File reading — user explicitly wants content
+    /\bcat\b/, /\bhead\b/, /\btail\b/, /\bbat\b/, /\bless\b/, /\bmore\b/,
+    // Git review commands — truncating diffs/patches loses semantic meaning
+    /\bgit\s+diff\b/, /\bgit\s+show\b/, /\bgit\s+log\s+-p\b/, /\bgit\s+log\s+--patch\b/,
+    // Summary/report commands — summarizing a summary is pointless
+    /\bsummary\b/i, /\bstatus\b/i, /\breport\b/i, /\bstats\b/i,
+    /\bweek\b/i, /\btoday\b/i, /\bdashboard\b/i,
+];
+/** Check if output should use lazy mode */
+export function shouldBeLazy(output, command) {
+    // Never lazify explicit read commands or summary commands
+    if (command && PASSTHROUGH_COMMANDS.some(p => p.test(command)))
+        return false;
+    return output.split("\n").filter(l => l.trim()).length > LAZY_THRESHOLD;
+}
+/** Convert large output to lazy format: count + sample + categories */
+export function toLazy(output, command) {
+    const lines = output.split("\n").filter(l => l.trim());
+    const sample = lines.slice(0, 20);
+    // Try to categorize by directory (for file-like output)
+    const categories = {};
+    const isFilePaths = lines.filter(l => l.includes("/")).length > lines.length * 0.5;
+    if (isFilePaths) {
+        for (const line of lines) {
+            const dir = dirname(line.trim()) || ".";
+            // Group by top-level dir
+            const topDir = dir.split("/").slice(0, 2).join("/");
+            categories[topDir] = (categories[topDir] ?? 0) + 1;
+        }
+    }
+    return {
+        lazy: true,
+        count: lines.length,
+        sample,
+        categories: Object.keys(categories).length > 1 ? categories : undefined,
+        hint: `${lines.length} results. Showing first 20. Use a more specific query to narrow results.`,
+    };
+}
+/** Get a slice of output */
+export function getSlice(output, offset, limit) {
+    const allLines = output.split("\n").filter(l => l.trim());
+    const slice = allLines.slice(offset, offset + limit);
+    return {
+        lines: slice,
+        total: allLines.length,
+        hasMore: offset + limit < allLines.length,
+    };
+}

package/dist/line-dedup.js

@@ -0,0 +1,59 @@
+// Cross-command line deduplication — track lines already shown to agent
+// When new output contains >50% already-seen lines, suppress them
+const seenLines = new Set();
+const MAX_SEEN = 5000;
+function normalize(line) {
+    return line.trim().toLowerCase();
+}
+/** Deduplicate output lines against session history */
+export function dedup(output) {
+    const lines = output.split("\n");
+    if (lines.length < 5) {
+        // Short output — add to seen, don't dedup
+        for (const l of lines) {
+            if (l.trim())
+                seenLines.add(normalize(l));
+        }
+        return { output, novelCount: lines.length, seenCount: 0, deduplicated: false };
+    }
+    let novelCount = 0;
+    let seenCount = 0;
+    const novel = [];
+    for (const line of lines) {
+        const norm = normalize(line);
+        if (!norm) {
+            novel.push(line);
+            continue;
+        }
+        if (seenLines.has(norm)) {
+            seenCount++;
+        }
+        else {
+            novelCount++;
+            novel.push(line);
+            seenLines.add(norm);
+        }
+    }
+    // Evict oldest if too large
+    if (seenLines.size > MAX_SEEN) {
+        const entries = [...seenLines];
+        for (let i = 0; i < entries.length - MAX_SEEN; i++) {
+            seenLines.delete(entries[i]);
+        }
+    }
+    // Only dedup if >50% were already seen
+    if (seenCount > lines.length * 0.5) {
+        const result = novel.join("\n");
+        return { output: result + `\n(${seenCount} lines already shown, omitted)`, novelCount, seenCount, deduplicated: true };
+    }
+    // Add all to seen but return full output
+    for (const l of lines) {
+        if (l.trim())
+            seenLines.add(normalize(l));
+    }
+    return { output, novelCount: lines.length, seenCount: 0, deduplicated: false };
+}
+/** Clear dedup history */
+export function clearDedup() {
+    seenLines.clear();
+}