@hasna/terminal 1.6.6 → 2.0.0

package/dist/cli.js

@@ -379,6 +379,32 @@ else if (args[0] === "symbols" && args[1]) {
         }
     }
 }
+// ── History command ──────────────────────────────────────────────────────────
+else if (args[0] === "history") {
+    const { loadContext } = await import("./session-context.js");
+    const entries = loadContext();
+    if (entries.length === 0) {
+        console.log("No recent history.");
+    }
+    else {
+        for (const e of entries) {
+            const time = new Date(e.timestamp).toLocaleTimeString();
+            console.log(`  ${time}  ${e.prompt}`);
+            console.log(`    $ ${e.command}`);
+        }
+    }
+}
+// ── Explain command ─────────────────────────────────────────────────────────
+else if (args[0] === "explain" && args[1]) {
+    const command = args.slice(1).join(" ");
+    if (!process.env.ANTHROPIC_API_KEY && !process.env.CEREBRAS_API_KEY) {
+        console.error("explain requires an API key");
+        process.exit(1);
+    }
+    const { explainCommand } = await import("./ai.js");
+    const explanation = await explainCommand(command);
+    console.log(explanation);
+}
 // ── Snapshot command ─────────────────────────────────────────────────────────
 else if (args[0] === "snapshot") {
     const { captureSnapshot } = await import("./snapshots.js");
@@ -394,13 +420,7 @@ else if (args[0] === "project" && args[1] === "init") {
 else if (args.length > 0) {
     // Everything that doesn't match a subcommand is treated as natural language
     const prompt = args.join(" ");
-    if (!process.env.ANTHROPIC_API_KEY && !process.env.CEREBRAS_API_KEY) {
-        console.error("terminal: No API key found.");
-        console.error("Set one of:");
-        console.error("  export CEREBRAS_API_KEY=your_key  (free, open-source)");
-        console.error("  export ANTHROPIC_API_KEY=your_key  (Claude)");
-        process.exit(1);
-    }
+    const offlineMode = !process.env.ANTHROPIC_API_KEY && !process.env.CEREBRAS_API_KEY;
     const { translateToCommand, checkPermissions, isIrreversible } = await import("./ai.js");
     const { execSync } = await import("child_process");
     const { compress, stripAnsi } = await import("./compression.js");
@@ -413,32 +433,63 @@ else if (args.length > 0) {
     const { isTestOutput, trackTests, formatWatchResult } = await import("./test-watchlist.js");
     const { detectLoop } = await import("./loop-detector.js");
     const { loadConfig } = await import("./history.js");
+    const { loadContext, saveContext, formatContext } = await import("./session-context.js");
+    const { getLearned, recordMapping } = await import("./usage-cache.js");
     const config = loadConfig();
     const perms = config.permissions;
-    // Step 1: AI translates NL → shell command
+    const sessionCtx = formatContext();
+    // Check usage learning cache first (zero AI cost for repeated queries)
+    const learned = getLearned(prompt);
+    if (learned && !offlineMode) {
+        console.error(`[open-terminal] cached: $ ${learned}`);
+    }
+    // Step 1: AI translates NL → shell command (with session context for follow-ups)
     let command;
-    try {
-        command = await translateToCommand(prompt, perms, []);
+    if (offlineMode) {
+        // Offline: treat prompt as literal command, apply noise filter only
+        console.error("[open-terminal] offline mode (no API key) — running as literal command");
+        command = prompt;
     }
-    catch (e) {
-        // If BLOCKED, try fallback: read README or package.json for conceptual questions
-        if (e.message?.startsWith("BLOCKED:")) {
-            try {
-                const { existsSync, readFileSync } = await import("fs");
-                if (existsSync("README.md")) {
-                    const readme = readFileSync("README.md", "utf8").slice(0, 3000);
-                    const processed = await processOutput("cat README.md", readme, prompt);
-                    if (processed.aiProcessed) {
-                        console.log(processed.summary);
-                        process.exit(0);
+    else if (learned) {
+        command = learned;
+    }
+    else {
+        try {
+            command = await translateToCommand(sessionCtx ? `${prompt}\n${sessionCtx}` : prompt, perms, []);
+        }
+        catch (e) {
+            // If BLOCKED, try README fallback ONLY for conceptual questions (not file access)
+            if (e.message?.startsWith("BLOCKED:")) {
+                const isConceptual = /\b(explain|why|what does|how does|describe|architecture|overview|summary)\b/i.test(prompt);
+                const isFileAccess = /\b(cat|show|read|find|ls|list)\b.*\b(\.\w+\/|src\/|packages\/)/i.test(prompt);
+                if (isConceptual && !isFileAccess) {
+                    try {
+                        const { existsSync, readFileSync } = await import("fs");
+                        if (existsSync("README.md")) {
+                            const readme = readFileSync("README.md", "utf8").slice(0, 3000);
+                            const processed = await processOutput("cat README.md", readme, prompt);
+                            if (processed.aiProcessed) {
+                                console.log(processed.summary);
+                                process.exit(0);
+                            }
+                        }
                     }
+                    catch { }
                 }
             }
-            catch { }
+            // "I don't know" honesty — better than wrong answer
+            if (e.message?.startsWith("BLOCKED:")) {
+                console.log(`I don't know how to do this with shell commands. Try running it directly.`);
+            }
+            else {
+                console.error(e.message);
+            }
+            process.exit(1);
         }
-        console.error(e.message);
-        process.exit(1);
-    }
+    } // close the else (learned/offline) block
+    // Record the mapping for usage learning
+    if (!offlineMode && !learned)
+        recordMapping(prompt, command);
     // Check permissions
     const blocked = checkPermissions(command, perms);
     if (blocked) {
@@ -504,6 +555,7 @@ else if (args.length > 0) {
         const clean = stripNoise(stripAnsi(raw)).cleaned;
         const rawTokens = estimateTokens(raw);
         recordUsage(rawTokens);
+        saveContext(prompt, actualCmd, clean.slice(0, 500));
         // Test output detection
         // Test output: skip watchlist, let AI framing handle it
         // The AI reads "42 pass, 0 fail" better than regex parsing bun's mixed output
@@ -544,6 +596,23 @@ else if (args.length > 0) {
         const errStdout = e.stdout?.toString() ?? "";
         const errStderr = e.stderr?.toString() ?? "";
         if (e.status === 1 && !errStdout.trim() && !errStderr.trim()) {
+            // Empty result — retry with broader scope before giving up
+            if (!actualCmd.includes("#(broadened)")) {
+                try {
+                    const broaderCmd = await translateToCommand(`${prompt} (Previous command found NOTHING. Try searching a BROADER scope: use . or packages/ instead of src/. Use simpler grep pattern.)`, perms, []);
+                    if (broaderCmd && !isIrreversible(broaderCmd) && !checkPermissions(broaderCmd, perms)) {
+                        console.error(`[open-terminal] broadening search...`);
+                        const broaderResult = execSync(broaderCmd + " #(broadened)", { encoding: "utf8", maxBuffer: 10 * 1024 * 1024, cwd: process.cwd() });
+                        const broaderClean = stripNoise(stripAnsi(broaderResult)).cleaned;
+                        if (broaderClean.trim()) {
+                            const processed = await processOutput(broaderCmd, broaderClean, prompt);
+                            console.log(processed.aiProcessed ? processed.summary : broaderClean);
+                            process.exit(0);
+                        }
+                    }
+                }
+                catch { /* broader also failed */ }
+            }
             console.log(`No results found for: ${prompt}`);
             process.exit(0);
         }

package/dist/search/semantic.js

@@ -61,6 +61,61 @@ function extractSymbols(filePath) {
     const lines = content.split("\n");
     const symbols = [];
     const file = filePath;
+    const ext = filePath.match(/\.(\w+)$/)?.[1] ?? "";
+    // Python support
+    if (ext === "py") {
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const defMatch = line.match(/^(\s*)(?:async\s+)?def\s+(\w+)\s*\(/);
+            if (defMatch) {
+                symbols.push({ name: defMatch[2], kind: "function", file, line: i + 1, signature: line.trim(), exported: !defMatch[2].startsWith("_") });
+            }
+            const classMatch = line.match(/^class\s+(\w+)/);
+            if (classMatch) {
+                symbols.push({ name: classMatch[1], kind: "class", file, line: i + 1, signature: line.trim(), exported: true });
+            }
+        }
+        return symbols;
+    }
+    // Go support
+    if (ext === "go") {
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const funcMatch = line.match(/^func\s+(?:\(\w+\s+\*?\w+\)\s+)?(\w+)\s*\(/);
+            if (funcMatch) {
+                symbols.push({ name: funcMatch[1], kind: "function", file, line: i + 1, signature: line.trim(), exported: /^[A-Z]/.test(funcMatch[1]) });
+            }
+            const typeMatch = line.match(/^type\s+(\w+)\s+(struct|interface)/);
+            if (typeMatch) {
+                symbols.push({ name: typeMatch[1], kind: typeMatch[2] === "interface" ? "interface" : "class", file, line: i + 1, signature: line.trim(), exported: /^[A-Z]/.test(typeMatch[1]) });
+            }
+        }
+        return symbols;
+    }
+    // Rust support
+    if (ext === "rs") {
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            const fnMatch = line.match(/^\s*(?:pub\s+)?(?:async\s+)?fn\s+(\w+)/);
+            if (fnMatch) {
+                symbols.push({ name: fnMatch[1], kind: "function", file, line: i + 1, signature: line.trim(), exported: line.includes("pub") });
+            }
+            const structMatch = line.match(/^\s*(?:pub\s+)?struct\s+(\w+)/);
+            if (structMatch) {
+                symbols.push({ name: structMatch[1], kind: "class", file, line: i + 1, signature: line.trim(), exported: line.includes("pub") });
+            }
+            const enumMatch = line.match(/^\s*(?:pub\s+)?enum\s+(\w+)/);
+            if (enumMatch) {
+                symbols.push({ name: enumMatch[1], kind: "type", file, line: i + 1, signature: line.trim(), exported: line.includes("pub") });
+            }
+            const traitMatch = line.match(/^\s*(?:pub\s+)?trait\s+(\w+)/);
+            if (traitMatch) {
+                symbols.push({ name: traitMatch[1], kind: "interface", file, line: i + 1, signature: line.trim(), exported: line.includes("pub") });
+            }
+        }
+        return symbols;
+    }
+    // TypeScript/JavaScript (default)
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         const lineNum = i + 1;

package/dist/session-context.js

@@ -0,0 +1,55 @@
+// Session context — stores last N command+output pairs for follow-up queries
+// Enables: terminal "show auth code" → terminal "explain that function"
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+const DIR = join(homedir(), ".terminal");
+const CTX_FILE = join(DIR, "session-context.json");
+const MAX_ENTRIES = 5;
+function ensureDir() {
+    if (!existsSync(DIR))
+        mkdirSync(DIR, { recursive: true });
+}
+/** Load session context */
+export function loadContext() {
+    ensureDir();
+    if (!existsSync(CTX_FILE))
+        return [];
+    try {
+        const entries = JSON.parse(readFileSync(CTX_FILE, "utf8"));
+        // Only return entries from last 30 minutes (session freshness)
+        const cutoff = Date.now() - 30 * 60 * 1000;
+        return entries.filter(e => e.timestamp > cutoff).slice(-MAX_ENTRIES);
+    }
+    catch {
+        return [];
+    }
+}
+/** Save a command to session context */
+export function saveContext(prompt, command, output) {
+    ensureDir();
+    const entries = loadContext();
+    entries.push({
+        prompt,
+        command,
+        output: output.slice(0, 500),
+        timestamp: Date.now(),
+    });
+    // Keep only last N
+    const trimmed = entries.slice(-MAX_ENTRIES);
+    writeFileSync(CTX_FILE, JSON.stringify(trimmed, null, 2));
+}
+/** Format context for AI prompt injection */
+export function formatContext() {
+    const entries = loadContext();
+    if (entries.length === 0)
+        return "";
+    const lines = ["\nRECENT SESSION CONTEXT (for follow-up references like 'that', 'it', 'the same'):"];
+    for (const e of entries.slice(-3)) {
+        lines.push(`> ${e.prompt}`);
+        lines.push(`$ ${e.command}`);
+        if (e.output)
+            lines.push(e.output.slice(0, 200));
+    }
+    return lines.join("\n");
+}

package/dist/usage-cache.js

@@ -0,0 +1,65 @@
+// Usage learning cache — zero-cost repeated queries
+// After 3 identical prompt→command mappings, cache locally
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { createHash } from "crypto";
+const DIR = join(homedir(), ".terminal");
+const CACHE_FILE = join(DIR, "learned.json");
+function ensureDir() {
+    if (!existsSync(DIR))
+        mkdirSync(DIR, { recursive: true });
+}
+function hash(s) {
+    return createHash("md5").update(s).digest("hex").slice(0, 12);
+}
+function cacheKey(prompt) {
+    const projectHash = hash(process.cwd());
+    const promptHash = hash(prompt.toLowerCase().trim());
+    return `${projectHash}:${promptHash}`;
+}
+function loadCache() {
+    ensureDir();
+    if (!existsSync(CACHE_FILE))
+        return {};
+    try {
+        return JSON.parse(readFileSync(CACHE_FILE, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function saveCache(cache) {
+    ensureDir();
+    writeFileSync(CACHE_FILE, JSON.stringify(cache));
+}
+/** Check if we have a learned command for this prompt (3+ identical mappings) */
+export function getLearned(prompt) {
+    const key = cacheKey(prompt);
+    const cache = loadCache();
+    const entry = cache[key];
+    if (entry && entry.count >= 3)
+        return entry.command;
+    return null;
+}
+/** Record a prompt→command mapping */
+export function recordMapping(prompt, command) {
+    const key = cacheKey(prompt);
+    const cache = loadCache();
+    const existing = cache[key];
+    if (existing && existing.command === command) {
+        existing.count++;
+        existing.lastUsed = Date.now();
+    }
+    else {
+        cache[key] = { command, count: 1, lastUsed: Date.now() };
+    }
+    saveCache(cache);
+}
+/** Get cache stats */
+export function learnedStats() {
+    const cache = loadCache();
+    const entries = Object.keys(cache).length;
+    const cached = Object.values(cache).filter(e => e.count >= 3).length;
+    return { entries, cached };
+}

package/package.json

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

package/src/cli.tsx

@@ -352,6 +352,33 @@ else if (args[0] === "symbols" && args[1]) {
   }
 }
 
+// ── History command ──────────────────────────────────────────────────────────
+
+else if (args[0] === "history") {
+  const { loadContext } = await import("./session-context.js");
+  const entries = loadContext();
+  if (entries.length === 0) { console.log("No recent history."); }
+  else {
+    for (const e of entries) {
+      const time = new Date(e.timestamp).toLocaleTimeString();
+      console.log(`  ${time}  ${e.prompt}`);
+      console.log(`    $ ${e.command}`);
+    }
+  }
+}
+
+// ── Explain command ─────────────────────────────────────────────────────────
+
+else if (args[0] === "explain" && args[1]) {
+  const command = args.slice(1).join(" ");
+  if (!process.env.ANTHROPIC_API_KEY && !process.env.CEREBRAS_API_KEY) {
+    console.error("explain requires an API key"); process.exit(1);
+  }
+  const { explainCommand } = await import("./ai.js");
+  const explanation = await explainCommand(command);
+  console.log(explanation);
+}
+
 // ── Snapshot command ─────────────────────────────────────────────────────────
 
 else if (args[0] === "snapshot") {
@@ -373,13 +400,7 @@ else if (args.length > 0) {
   // Everything that doesn't match a subcommand is treated as natural language
   const prompt = args.join(" ");
 
-  if (!process.env.ANTHROPIC_API_KEY && !process.env.CEREBRAS_API_KEY) {
-    console.error("terminal: No API key found.");
-    console.error("Set one of:");
-    console.error("  export CEREBRAS_API_KEY=your_key  (free, open-source)");
-    console.error("  export ANTHROPIC_API_KEY=your_key  (Claude)");
-    process.exit(1);
-  }
+  const offlineMode = !process.env.ANTHROPIC_API_KEY && !process.env.CEREBRAS_API_KEY;
 
   const { translateToCommand, checkPermissions, isIrreversible } = await import("./ai.js");
   const { execSync } = await import("child_process");
@@ -393,32 +414,62 @@ else if (args.length > 0) {
   const { isTestOutput, trackTests, formatWatchResult } = await import("./test-watchlist.js");
   const { detectLoop } = await import("./loop-detector.js");
   const { loadConfig } = await import("./history.js");
+  const { loadContext, saveContext, formatContext } = await import("./session-context.js");
+  const { getLearned, recordMapping } = await import("./usage-cache.js");
 
   const config = loadConfig();
   const perms = config.permissions;
+  const sessionCtx = formatContext();
+
+  // Check usage learning cache first (zero AI cost for repeated queries)
+  const learned = getLearned(prompt);
+  if (learned && !offlineMode) {
+    console.error(`[open-terminal] cached: $ ${learned}`);
+  }
 
-  // Step 1: AI translates NL → shell command
+  // Step 1: AI translates NL → shell command (with session context for follow-ups)
   let command: string;
-  try {
-    command = await translateToCommand(prompt, perms, []);
+
+  if (offlineMode) {
+    // Offline: treat prompt as literal command, apply noise filter only
+    console.error("[open-terminal] offline mode (no API key) — running as literal command");
+    command = prompt;
+  } else if (learned) {
+    command = learned;
+  } else {
+    try {
+      command = await translateToCommand(sessionCtx ? `${prompt}\n${sessionCtx}` : prompt, perms, []);
   } catch (e: any) {
-    // If BLOCKED, try fallback: read README or package.json for conceptual questions
+    // If BLOCKED, try README fallback ONLY for conceptual questions (not file access)
     if (e.message?.startsWith("BLOCKED:")) {
-      try {
-        const { existsSync, readFileSync } = await import("fs");
-        if (existsSync("README.md")) {
-          const readme = readFileSync("README.md", "utf8").slice(0, 3000);
-          const processed = await processOutput("cat README.md", readme, prompt);
-          if (processed.aiProcessed) {
-            console.log(processed.summary);
-            process.exit(0);
+      const isConceptual = /\b(explain|why|what does|how does|describe|architecture|overview|summary)\b/i.test(prompt);
+      const isFileAccess = /\b(cat|show|read|find|ls|list)\b.*\b(\.\w+\/|src\/|packages\/)/i.test(prompt);
+      if (isConceptual && !isFileAccess) {
+        try {
+          const { existsSync, readFileSync } = await import("fs");
+          if (existsSync("README.md")) {
+            const readme = readFileSync("README.md", "utf8").slice(0, 3000);
+            const processed = await processOutput("cat README.md", readme, prompt);
+            if (processed.aiProcessed) {
+              console.log(processed.summary);
+              process.exit(0);
+            }
           }
-        }
-      } catch {}
+        } catch {}
+      }
+    }
+    // "I don't know" honesty — better than wrong answer
+    if (e.message?.startsWith("BLOCKED:")) {
+      console.log(`I don't know how to do this with shell commands. Try running it directly.`);
+    } else {
+      console.error(e.message);
     }
-    console.error(e.message);
     process.exit(1);
   }
+  } // close the else (learned/offline) block
+
+  // Record the mapping for usage learning
+  if (!offlineMode && !learned) recordMapping(prompt, command);
 
   // Check permissions
   const blocked = checkPermissions(command, perms);
@@ -489,6 +540,7 @@ else if (args.length > 0) {
     const clean = stripNoise(stripAnsi(raw)).cleaned;
     const rawTokens = estimateTokens(raw);
     recordUsage(rawTokens);
+    saveContext(prompt, actualCmd, clean.slice(0, 500));
 
     // Test output detection
     // Test output: skip watchlist, let AI framing handle it
@@ -527,6 +579,25 @@ else if (args.length > 0) {
     const errStdout = e.stdout?.toString() ?? "";
     const errStderr = e.stderr?.toString() ?? "";
     if (e.status === 1 && !errStdout.trim() && !errStderr.trim()) {
+      // Empty result — retry with broader scope before giving up
+      if (!actualCmd.includes("#(broadened)")) {
+        try {
+          const broaderCmd = await translateToCommand(
+            `${prompt} (Previous command found NOTHING. Try searching a BROADER scope: use . or packages/ instead of src/. Use simpler grep pattern.)`,
+            perms, []
+          );
+          if (broaderCmd && !isIrreversible(broaderCmd) && !checkPermissions(broaderCmd, perms)) {
+            console.error(`[open-terminal] broadening search...`);
+            const broaderResult = execSync(broaderCmd + " #(broadened)", { encoding: "utf8", maxBuffer: 10 * 1024 * 1024, cwd: process.cwd() });
+            const broaderClean = stripNoise(stripAnsi(broaderResult)).cleaned;
+            if (broaderClean.trim()) {
+              const processed = await processOutput(broaderCmd, broaderClean, prompt);
+              console.log(processed.aiProcessed ? processed.summary : broaderClean);
+              process.exit(0);
+            }
+          }
+        } catch { /* broader also failed */ }
+      }
       console.log(`No results found for: ${prompt}`);
       process.exit(0);
     }

package/src/search/semantic.ts

@@ -77,7 +77,65 @@ function extractSymbols(filePath: string): CodeSymbol[] {
   const lines = content.split("\n");
   const symbols: CodeSymbol[] = [];
   const file = filePath;
+  const ext = filePath.match(/\.(\w+)$/)?.[1] ?? "";
+
+  // Python support
+  if (ext === "py") {
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const defMatch = line.match(/^(\s*)(?:async\s+)?def\s+(\w+)\s*\(/);
+      if (defMatch) {
+        symbols.push({ name: defMatch[2], kind: "function", file, line: i + 1, signature: line.trim(), exported: !defMatch[2].startsWith("_") });
+      }
+      const classMatch = line.match(/^class\s+(\w+)/);
+      if (classMatch) {
+        symbols.push({ name: classMatch[1], kind: "class", file, line: i + 1, signature: line.trim(), exported: true });
+      }
+    }
+    return symbols;
+  }
+
+  // Go support
+  if (ext === "go") {
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const funcMatch = line.match(/^func\s+(?:\(\w+\s+\*?\w+\)\s+)?(\w+)\s*\(/);
+      if (funcMatch) {
+        symbols.push({ name: funcMatch[1], kind: "function", file, line: i + 1, signature: line.trim(), exported: /^[A-Z]/.test(funcMatch[1]) });
+      }
+      const typeMatch = line.match(/^type\s+(\w+)\s+(struct|interface)/);
+      if (typeMatch) {
+        symbols.push({ name: typeMatch[1], kind: typeMatch[2] === "interface" ? "interface" : "class", file, line: i + 1, signature: line.trim(), exported: /^[A-Z]/.test(typeMatch[1]) });
+      }
+    }
+    return symbols;
+  }
+
+  // Rust support
+  if (ext === "rs") {
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const fnMatch = line.match(/^\s*(?:pub\s+)?(?:async\s+)?fn\s+(\w+)/);
+      if (fnMatch) {
+        symbols.push({ name: fnMatch[1], kind: "function", file, line: i + 1, signature: line.trim(), exported: line.includes("pub") });
+      }
+      const structMatch = line.match(/^\s*(?:pub\s+)?struct\s+(\w+)/);
+      if (structMatch) {
+        symbols.push({ name: structMatch[1], kind: "class", file, line: i + 1, signature: line.trim(), exported: line.includes("pub") });
+      }
+      const enumMatch = line.match(/^\s*(?:pub\s+)?enum\s+(\w+)/);
+      if (enumMatch) {
+        symbols.push({ name: enumMatch[1], kind: "type", file, line: i + 1, signature: line.trim(), exported: line.includes("pub") });
+      }
+      const traitMatch = line.match(/^\s*(?:pub\s+)?trait\s+(\w+)/);
+      if (traitMatch) {
+        symbols.push({ name: traitMatch[1], kind: "interface", file, line: i + 1, signature: line.trim(), exported: line.includes("pub") });
+      }
+    }
+    return symbols;
+  }
 
+  // TypeScript/JavaScript (default)
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
     const lineNum = i + 1;

package/src/session-context.ts

@@ -0,0 +1,61 @@
+// Session context — stores last N command+output pairs for follow-up queries
+// Enables: terminal "show auth code" → terminal "explain that function"
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+
+const DIR = join(homedir(), ".terminal");
+const CTX_FILE = join(DIR, "session-context.json");
+const MAX_ENTRIES = 5;
+
+interface ContextEntry {
+  prompt: string;
+  command: string;
+  output: string; // first 500 chars
+  timestamp: number;
+}
+
+function ensureDir() {
+  if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true });
+}
+
+/** Load session context */
+export function loadContext(): ContextEntry[] {
+  ensureDir();
+  if (!existsSync(CTX_FILE)) return [];
+  try {
+    const entries = JSON.parse(readFileSync(CTX_FILE, "utf8")) as ContextEntry[];
+    // Only return entries from last 30 minutes (session freshness)
+    const cutoff = Date.now() - 30 * 60 * 1000;
+    return entries.filter(e => e.timestamp > cutoff).slice(-MAX_ENTRIES);
+  } catch { return []; }
+}
+
+/** Save a command to session context */
+export function saveContext(prompt: string, command: string, output: string): void {
+  ensureDir();
+  const entries = loadContext();
+  entries.push({
+    prompt,
+    command,
+    output: output.slice(0, 500),
+    timestamp: Date.now(),
+  });
+  // Keep only last N
+  const trimmed = entries.slice(-MAX_ENTRIES);
+  writeFileSync(CTX_FILE, JSON.stringify(trimmed, null, 2));
+}
+
+/** Format context for AI prompt injection */
+export function formatContext(): string {
+  const entries = loadContext();
+  if (entries.length === 0) return "";
+  const lines: string[] = ["\nRECENT SESSION CONTEXT (for follow-up references like 'that', 'it', 'the same'):"];
+  for (const e of entries.slice(-3)) {
+    lines.push(`> ${e.prompt}`);
+    lines.push(`$ ${e.command}`);
+    if (e.output) lines.push(e.output.slice(0, 200));
+  }
+  return lines.join("\n");
+}

package/src/usage-cache.ts

@@ -0,0 +1,74 @@
+// Usage learning cache — zero-cost repeated queries
+// After 3 identical prompt→command mappings, cache locally
+
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { createHash } from "crypto";
+
+const DIR = join(homedir(), ".terminal");
+const CACHE_FILE = join(DIR, "learned.json");
+
+interface LearnedEntry {
+  command: string;
+  count: number;
+  lastUsed: number;
+}
+
+type LearnedCache = Record<string, LearnedEntry>; // key = projectHash:promptHash
+
+function ensureDir() {
+  if (!existsSync(DIR)) mkdirSync(DIR, { recursive: true });
+}
+
+function hash(s: string): string {
+  return createHash("md5").update(s).digest("hex").slice(0, 12);
+}
+
+function cacheKey(prompt: string): string {
+  const projectHash = hash(process.cwd());
+  const promptHash = hash(prompt.toLowerCase().trim());
+  return `${projectHash}:${promptHash}`;
+}
+
+function loadCache(): LearnedCache {
+  ensureDir();
+  if (!existsSync(CACHE_FILE)) return {};
+  try { return JSON.parse(readFileSync(CACHE_FILE, "utf8")); } catch { return {}; }
+}
+
+function saveCache(cache: LearnedCache): void {
+  ensureDir();
+  writeFileSync(CACHE_FILE, JSON.stringify(cache));
+}
+
+/** Check if we have a learned command for this prompt (3+ identical mappings) */
+export function getLearned(prompt: string): string | null {
+  const key = cacheKey(prompt);
+  const cache = loadCache();
+  const entry = cache[key];
+  if (entry && entry.count >= 3) return entry.command;
+  return null;
+}
+
+/** Record a prompt→command mapping */
+export function recordMapping(prompt: string, command: string): void {
+  const key = cacheKey(prompt);
+  const cache = loadCache();
+  const existing = cache[key];
+  if (existing && existing.command === command) {
+    existing.count++;
+    existing.lastUsed = Date.now();
+  } else {
+    cache[key] = { command, count: 1, lastUsed: Date.now() };
+  }
+  saveCache(cache);
+}
+
+/** Get cache stats */
+export function learnedStats(): { entries: number; cached: number } {
+  const cache = loadCache();
+  const entries = Object.keys(cache).length;
+  const cached = Object.values(cache).filter(e => e.count >= 3).length;
+  return { entries, cached };
+}