@hasna/terminal 4.3.0 → 4.3.2

package/src/mcp/tools/helpers.ts

@@ -0,0 +1,92 @@
+// Shared helpers for all MCP tools
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { spawn } from "child_process";
+import { stripNoise } from "../../noise-filter.js";
+import { rewriteCommand } from "../../command-rewriter.js";
+import { invalidateBootCache } from "../../session-boot.js";
+import { logInteraction } from "../../sessions-db.js";
+import { join } from "path";
+
+export { z } from "zod";
+
+export interface ExecResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  duration: number;
+  rewritten?: string;
+}
+
+export interface LogCallData {
+  command?: string;
+  outputTokens?: number;
+  tokensSaved?: number;
+  durationMs?: number;
+  exitCode?: number;
+  aiProcessed?: boolean;
+  model?: string;
+}
+
+export interface ToolHelpers {
+  exec: (command: string, cwd?: string, timeout?: number, allowRewrite?: boolean) => Promise<ExecResult>;
+  resolvePath: (p: string, cwd?: string) => string;
+  logCall: (tool: string, data: LogCallData) => void;
+  sessionId: string;
+}
+
+/** Create shared helpers for tool modules */
+export function createHelpers(sessionId: string): ToolHelpers {
+  function exec(command: string, cwd?: string, timeout?: number, allowRewrite: boolean = false): Promise<ExecResult> {
+    const rw = allowRewrite ? rewriteCommand(command) : { changed: false, rewritten: command };
+    const actualCommand = rw.changed ? rw.rewritten : command;
+    return new Promise((resolve) => {
+      const start = Date.now();
+      const proc = spawn("/bin/zsh", ["-c", actualCommand], {
+        cwd: cwd ?? process.cwd(),
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+
+      let stdout = "";
+      let stderr = "";
+
+      proc.stdout?.on("data", (d: Buffer) => { stdout += d.toString(); });
+      proc.stderr?.on("data", (d: Buffer) => { stderr += d.toString(); });
+
+      const timer = timeout ? setTimeout(() => { try { proc.kill("SIGTERM"); } catch {} }, timeout) : null;
+
+      proc.on("close", (code) => {
+        if (timer) clearTimeout(timer);
+        const cleanStdout = stripNoise(stdout).cleaned;
+        const cleanStderr = stripNoise(stderr).cleaned;
+        if (/\bgit\s+(commit|checkout|branch|merge|reset|push|pull|rebase|stash)\b/.test(actualCommand)) {
+          invalidateBootCache();
+        }
+        resolve({ exitCode: code ?? 0, stdout: cleanStdout, stderr: cleanStderr, duration: Date.now() - start, rewritten: rw.changed ? rw.rewritten : undefined });
+      });
+    });
+  }
+
+  function resolvePath(p: string, cwd?: string): string {
+    if (!p) return cwd ?? process.cwd();
+    if (p.startsWith("/") || p.startsWith("~")) return p;
+    return join(cwd ?? process.cwd(), p);
+  }
+
+  function logCall(tool: string, data: LogCallData) {
+    try {
+      logInteraction(sessionId, {
+        nl: `[mcp:${tool}]${data.command ? ` ${data.command.slice(0, 200)}` : ""}`,
+        command: data.command?.slice(0, 500),
+        exitCode: data.exitCode,
+        tokensUsed: data.aiProcessed ? (data.outputTokens ?? 0) : 0,
+        tokensSaved: data.tokensSaved ?? 0,
+        durationMs: data.durationMs,
+        model: data.model,
+        cached: false,
+      });
+    } catch {}
+  }
+
+  return { exec, resolvePath, logCall, sessionId };
+}

package/src/mcp/tools/memory.ts

@@ -0,0 +1,172 @@
+// Memory tools: remember, recall, project_note, store_secret, list_secrets
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z, type ToolHelpers } from "./helpers.js";
+
+// Fallback memory store when mementos SDK not available
+function getLocalMemoryFile(): string {
+  const { join } = require("path");
+  return join(process.cwd(), ".terminal", "memories.json");
+}
+
+function loadLocalMemories(): { key: string; value: string; importance: number }[] {
+  const { existsSync, readFileSync } = require("fs");
+  const file = getLocalMemoryFile();
+  if (!existsSync(file)) return [];
+  try { return JSON.parse(readFileSync(file, "utf8")); } catch { return []; }
+}
+
+function saveLocalMemory(key: string, value: string, importance: number): void {
+  const { existsSync, writeFileSync, mkdirSync } = require("fs");
+  const { dirname } = require("path");
+  const file = getLocalMemoryFile();
+  const dir = dirname(file);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const memories = loadLocalMemories().filter(m => m.key !== key); // dedup by key
+  memories.push({ key, value, importance });
+  writeFileSync(file, JSON.stringify(memories, null, 2));
+}
+
+export function registerMemoryTools(server: McpServer, h: ToolHelpers): void {
+
+  // ── remember ──────────────────────────────────────────────────────────────
+
+  server.tool(
+    "remember",
+    "Save a learning about this project for future sessions. Persists across restarts. Use for: project patterns, conventions, toolchain quirks, architectural decisions.",
+    {
+      key: z.string().describe("Short key (e.g., 'test-command', 'deploy-process', 'auth-pattern')"),
+      value: z.string().describe("What to remember"),
+      importance: z.number().optional().describe("1-10, default 7"),
+    },
+    async ({ key, value, importance }) => {
+      const imp = importance ?? 7;
+      // Try mementos SDK first, fall back to local file
+      try {
+        const mementos = require("@hasna/mementos");
+        mementos.createMemory({ key, value, scope: "shared", category: "knowledge", importance: imp });
+      } catch {
+        saveLocalMemory(key, value, imp);
+      }
+      h.logCall("remember", { command: `remember: ${key}` });
+      return { content: [{ type: "text" as const, text: JSON.stringify({ saved: key }) }] };
+    }
+  );
+
+  // ── recall ────────────────────────────────────────────────────────────────
+
+  server.tool(
+    "recall",
+    "Recall project memories from previous sessions. Returns all saved learnings, patterns, and decisions for this project.",
+    {
+      search: z.string().optional().describe("Search query to filter memories"),
+      limit: z.number().optional().describe("Max memories to return (default: 20)"),
+    },
+    async ({ search, limit }) => {
+      let items: { key: string; value: string; importance: number }[] = [];
+      // Try mementos SDK first, fall back to local file
+      try {
+        const mementos = require("@hasna/mementos");
+        const memories = search
+          ? mementos.searchMemories(search, { limit: limit ?? 20 })
+          : mementos.listMemories({ scope: "shared", limit: limit ?? 20 });
+        items = (memories ?? []).map((m: any) => ({ key: m.key, value: m.value, importance: m.importance }));
+      } catch {
+        let local = loadLocalMemories();
+        if (search) {
+          const q = search.toLowerCase();
+          local = local.filter(m => m.key.toLowerCase().includes(q) || m.value.toLowerCase().includes(q));
+        }
+        items = local.slice(0, limit ?? 20);
+      }
+      h.logCall("recall", { command: `recall${search ? `: ${search}` : ""}` });
+      return { content: [{ type: "text" as const, text: JSON.stringify({ memories: items, total: items.length }) }] };
+    }
+  );
+
+  // ── project_note ──────────────────────────────────────────────────────────
+
+  server.tool(
+    "project_note",
+    "Save or recall notes about the current project. Persists across sessions. Agents pick up where they left off.",
+    {
+      save: z.string().optional().describe("Note to save"),
+      recall: z.boolean().optional().describe("Return all saved notes"),
+      clear: z.boolean().optional().describe("Clear all notes"),
+    },
+    async ({ save, recall, clear }) => {
+      const { existsSync, readFileSync, writeFileSync, mkdirSync } = await import("fs");
+      const { join } = await import("path");
+      const notesDir = join(process.cwd(), ".terminal");
+      const notesFile = join(notesDir, "notes.json");
+
+      let notes: { text: string; timestamp: string }[] = [];
+      if (existsSync(notesFile)) {
+        try { notes = JSON.parse(readFileSync(notesFile, "utf8")); } catch {}
+      }
+
+      if (clear) {
+        notes = [];
+        if (!existsSync(notesDir)) mkdirSync(notesDir, { recursive: true });
+        writeFileSync(notesFile, "[]");
+        return { content: [{ type: "text" as const, text: JSON.stringify({ cleared: true }) }] };
+      }
+
+      if (save) {
+        notes.push({ text: save, timestamp: new Date().toISOString() });
+        if (!existsSync(notesDir)) mkdirSync(notesDir, { recursive: true });
+        writeFileSync(notesFile, JSON.stringify(notes, null, 2));
+        h.logCall("project_note", { command: `save: ${save.slice(0, 80)}` });
+        return { content: [{ type: "text" as const, text: JSON.stringify({ saved: true, total: notes.length }) }] };
+      }
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({ notes, total: notes.length }) }] };
+    }
+  );
+
+  // ── store_secret ──────────────────────────────────────────────────────────
+
+  server.tool(
+    "store_secret",
+    "Store a secret for use in commands. Agent uses $NAME in commands, we resolve at execution and redact in output.",
+    {
+      name: z.string().describe("Secret name (e.g., JIRA_TOKEN)"),
+      value: z.string().describe("Secret value"),
+    },
+    async ({ name, value }) => {
+      const { existsSync, readFileSync, writeFileSync, chmodSync } = await import("fs");
+      const { join } = await import("path");
+      const { getTerminalDir } = await import("../../paths.js");
+      const secretsFile = join(getTerminalDir(), "secrets.json");
+      let secrets: Record<string, string> = {};
+      if (existsSync(secretsFile)) {
+        try { secrets = JSON.parse(readFileSync(secretsFile, "utf8")); } catch {}
+      }
+      secrets[name] = value;
+      writeFileSync(secretsFile, JSON.stringify(secrets, null, 2));
+      try { chmodSync(secretsFile, 0o600); } catch {}
+      h.logCall("store_secret", { command: `store ${name}` });
+      return { content: [{ type: "text" as const, text: JSON.stringify({ stored: name, hint: `Use $${name} in commands. Value will be resolved at execution and redacted in output.` }) }] };
+    }
+  );
+
+  // ── list_secrets ──────────────────────────────────────────────────────────
+
+  server.tool(
+    "list_secrets",
+    "List stored secret names (never values).",
+    async () => {
+      const { existsSync, readFileSync } = await import("fs");
+      const { join } = await import("path");
+      const { getTerminalDir } = await import("../../paths.js");
+      const secretsFile = join(getTerminalDir(), "secrets.json");
+      let names: string[] = [];
+      if (existsSync(secretsFile)) {
+        try { names = Object.keys(JSON.parse(readFileSync(secretsFile, "utf8"))); } catch {}
+      }
+      // Also show env vars that look like secrets
+      const envSecrets = Object.keys(process.env).filter(k => /API_KEY|TOKEN|SECRET|PASSWORD/i.test(k));
+      return { content: [{ type: "text" as const, text: JSON.stringify({ stored: names, environment: envSecrets }) }] };
+    }
+  );
+}

package/src/mcp/tools/meta.ts

@@ -0,0 +1,202 @@
+// Meta tools: token_stats, session_history, snapshot, watch, list_recipes, run_recipe, save_recipe, list_collections
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z, type ToolHelpers } from "./helpers.js";
+import { stripAnsi } from "../../compression.js";
+import { estimateTokens } from "../../tokens.js";
+import { processOutput } from "../../output-processor.js";
+import { listRecipes, listCollections, getRecipe, createRecipe } from "../../recipes/storage.js";
+import { substituteVariables } from "../../recipes/model.js";
+import { listSessions, getSessionInteractions, getSessionStats, getSessionEconomy } from "../../sessions-db.js";
+import { getEconomyStats } from "../../economy.js";
+import { captureSnapshot } from "../../snapshots.js";
+import { storeOutput } from "../../expand-store.js";
+
+export function registerMetaTools(server: McpServer, h: ToolHelpers): void {
+
+  // ── token_stats ───────────────────────────────────────────────────────────
+
+  server.tool(
+    "token_stats",
+    "Get full token economy — savings, costs, ROI. Includes round-trip multiplier (saved tokens repeated across ~5 turns).",
+    async () => {
+      const stats = getEconomyStats();
+      const { estimateSavingsUsd } = await import("../../economy.js");
+      const opus = estimateSavingsUsd(stats.totalTokensSaved, "anthropic-opus");
+      const sonnet = estimateSavingsUsd(stats.totalTokensSaved, "anthropic-sonnet");
+      const haiku = estimateSavingsUsd(stats.totalTokensSaved, "anthropic");
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        ...stats,
+        roundTrip: {
+          multiplier: 5,
+          billableTokensSaved: stats.totalTokensSaved * 5,
+          savingsUsd: { opus: opus.savingsUsd, sonnet: sonnet.savingsUsd, haiku: haiku.savingsUsd },
+        },
+        ratio: stats.totalTokensUsed > 0 ? Math.round((stats.totalTokensSaved / stats.totalTokensUsed) * 10) / 10 : 0,
+      }) }] };
+    }
+  );
+
+  // ── session_history ───────────────────────────────────────────────────────
+
+  server.tool(
+    "session_history",
+    "Query terminal session history — recent sessions, specific session details, or aggregate stats.",
+    {
+      action: z.enum(["list", "detail", "stats"]).describe("list=recent sessions, detail=specific session, stats=aggregates"),
+      sessionId: z.string().optional().describe("Session ID (for detail action)"),
+      limit: z.number().optional().describe("Max sessions to return (for list, default: 20)"),
+    },
+    async ({ action, sessionId, limit }) => {
+      if (action === "stats") {
+        return { content: [{ type: "text" as const, text: JSON.stringify(getSessionStats()) }] };
+      }
+      if (action === "detail" && sessionId) {
+        const interactions = getSessionInteractions(sessionId);
+        const economy = getSessionEconomy(sessionId);
+        return { content: [{ type: "text" as const, text: JSON.stringify({ interactions, economy }) }] };
+      }
+      const sessions = listSessions(limit ?? 20);
+      return { content: [{ type: "text" as const, text: JSON.stringify(sessions) }] };
+    }
+  );
+
+  // ── snapshot ──────────────────────────────────────────────────────────────
+
+  server.tool(
+    "snapshot",
+    "Capture a compact snapshot of terminal state (cwd, env, running processes, recent commands, recipes). Useful for agent context handoff.",
+    async () => {
+      const snap = captureSnapshot();
+      return { content: [{ type: "text" as const, text: JSON.stringify(snap) }] };
+    }
+  );
+
+  // ── watch ─────────────────────────────────────────────────────────────────
+
+  server.tool(
+    "watch",
+    "Run a task (test/build/lint/typecheck) on file change. Returns diff from last run. Agent stops polling — we push on change. Call watch_stop to end.",
+    {
+      task: z.enum(["test", "build", "lint", "typecheck"]).describe("Task to run on change"),
+      path: z.string().optional().describe("File or directory to watch (default: src/)"),
+      cwd: z.string().optional().describe("Working directory"),
+    },
+    async ({ task, path: watchPath, cwd }) => {
+      const workDir = cwd ?? process.cwd();
+      const target = h.resolvePath(watchPath ?? "src/", workDir);
+      const watchId = `${task}:${target}`;
+
+      // Run once immediately
+      const { existsSync } = await import("fs");
+      const { join } = await import("path");
+
+      let runner = "npm run";
+      if (existsSync(join(workDir, "bun.lockb")) || existsSync(join(workDir, "bun.lock"))) runner = "bun run";
+      else if (existsSync(join(workDir, "Cargo.toml"))) runner = "cargo";
+
+      const cmd = runner === "cargo" ? `cargo ${task}` : `${runner} ${task}`;
+      const result = await h.exec(cmd, workDir, 60000);
+      const output = (result.stdout + result.stderr).trim();
+      const processed = await processOutput(cmd, output);
+
+      // Store initial result for diffing
+      const detailKey = storeOutput(`watch:${task}`, output);
+
+      h.logCall("watch", { command: `watch ${task} ${target}`, exitCode: result.exitCode, durationMs: 0, aiProcessed: processed.aiProcessed });
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        watchId,
+        task,
+        watching: target,
+        initialRun: { exitCode: result.exitCode, summary: processed.summary, tokensSaved: processed.tokensSaved },
+        hint: "File watching active. Call execute_diff with the same command to get changes on next run.",
+      }) }] };
+    }
+  );
+
+  // ── list_recipes ──────────────────────────────────────────────────────────
+
+  server.tool(
+    "list_recipes",
+    "List saved command recipes. Optionally filter by collection or project.",
+    {
+      collection: z.string().optional().describe("Filter by collection name"),
+      project: z.string().optional().describe("Project path for project-scoped recipes"),
+    },
+    async ({ collection, project }) => {
+      let recipes = listRecipes(project);
+      if (collection) recipes = recipes.filter(r => r.collection === collection);
+      return { content: [{ type: "text" as const, text: JSON.stringify(recipes) }] };
+    }
+  );
+
+  // ── run_recipe ────────────────────────────────────────────────────────────
+
+  server.tool(
+    "run_recipe",
+    "Run a saved recipe by name with optional variable substitution.",
+    {
+      name: z.string().describe("Recipe name"),
+      variables: z.record(z.string(), z.string()).optional().describe("Variable values: {port: '3000'}"),
+      cwd: z.string().optional().describe("Working directory"),
+      format: z.enum(["raw", "json", "compressed"]).optional().describe("Output format"),
+    },
+    async ({ name, variables, cwd, format }) => {
+      const recipe = getRecipe(name, cwd);
+      if (!recipe) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ error: `Recipe '${name}' not found` }) }] };
+      }
+
+      const command = variables ? substituteVariables(recipe.command, variables) : recipe.command;
+      const result = await h.exec(command, cwd, 30000);
+      const output = (result.stdout + result.stderr).trim();
+
+      if (format === "json" || format === "compressed") {
+        const processed = await processOutput(command, output);
+        return { content: [{ type: "text" as const, text: JSON.stringify({
+          recipe: name, exitCode: result.exitCode, summary: processed.summary,
+          structured: processed.structured, duration: result.duration,
+          tokensSaved: processed.tokensSaved, aiProcessed: processed.aiProcessed,
+        }) }] };
+      }
+
+      return { content: [{ type: "text" as const, text: JSON.stringify({
+        recipe: name, exitCode: result.exitCode, output: stripAnsi(output), duration: result.duration,
+      }) }] };
+    }
+  );
+
+  // ── save_recipe ───────────────────────────────────────────────────────────
+
+  server.tool(
+    "save_recipe",
+    "Save a reusable command recipe. Variables in commands use {name} syntax.",
+    {
+      name: z.string().describe("Recipe name"),
+      command: z.string().describe("Shell command (use {var} for variables)"),
+      description: z.string().optional().describe("Description"),
+      collection: z.string().optional().describe("Collection to add to"),
+      project: z.string().optional().describe("Project path (for project-scoped recipe)"),
+      tags: z.array(z.string()).optional().describe("Tags"),
+    },
+    async ({ name, command, description, collection, project, tags }) => {
+      const recipe = createRecipe({ name, command, description, collection, project, tags });
+      return { content: [{ type: "text" as const, text: JSON.stringify(recipe) }] };
+    }
+  );
+
+  // ── list_collections ──────────────────────────────────────────────────────
+
+  server.tool(
+    "list_collections",
+    "List recipe collections.",
+    {
+      project: z.string().optional().describe("Project path"),
+    },
+    async ({ project }) => {
+      const collections = listCollections(project);
+      return { content: [{ type: "text" as const, text: JSON.stringify(collections) }] };
+    }
+  );
+}

package/src/mcp/tools/process.ts

@@ -0,0 +1,94 @@
+// Process tools: bg_start, bg_stop, bg_status, bg_logs, bg_wait_port
+
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z, type ToolHelpers } from "./helpers.js";
+import { bgStart, bgStatus, bgStop, bgLogs, bgWaitPort } from "../../supervisor.js";
+
+export function registerProcessTools(server: McpServer, h: ToolHelpers): void {
+
+  // ── bg_start ──────────────────────────────────────────────────────────────
+
+  server.tool(
+    "bg_start",
+    "Start a background process (e.g., dev server). Auto-detects port from command.",
+    {
+      command: z.string().describe("Command to run in background"),
+      cwd: z.string().optional().describe("Working directory"),
+    },
+    async ({ command, cwd }) => {
+      const result = bgStart(command, cwd);
+      return { content: [{ type: "text" as const, text: JSON.stringify(result) }] };
+    }
+  );
+
+  // ── bg_status ─────────────────────────────────────────────────────────────
+
+  server.tool(
+    "bg_status",
+    "List all managed background processes with status, ports, and recent output.",
+    async () => {
+      return { content: [{ type: "text" as const, text: JSON.stringify(bgStatus()) }] };
+    }
+  );
+
+  // ── bg_stop ───────────────────────────────────────────────────────────────
+
+  server.tool(
+    "bg_stop",
+    "Stop a managed background process by PID.",
+    { pid: z.number().describe("Process ID to stop") },
+    async ({ pid }) => {
+      const ok = bgStop(pid);
+      return { content: [{ type: "text" as const, text: JSON.stringify({ stopped: ok, pid }) }] };
+    }
+  );
+
+  // ── bg_logs ───────────────────────────────────────────────────────────────
+
+  server.tool(
+    "bg_logs",
+    "Get recent output lines from a background process.",
+    {
+      pid: z.number().describe("Process ID"),
+      tail: z.number().optional().describe("Number of lines (default: 20)"),
+    },
+    async ({ pid, tail }) => {
+      const lines = bgLogs(pid, tail);
+      return { content: [{ type: "text" as const, text: JSON.stringify({ pid, lines }) }] };
+    }
+  );
+
+  // ── bg_wait_port ──────────────────────────────────────────────────────────
+
+  server.tool(
+    "bg_wait_port",
+    "Wait for a port to start accepting connections. Useful after starting a dev server.",
+    {
+      port: z.number().describe("Port number to wait for"),
+      timeout: z.number().optional().describe("Timeout in ms (default: 30000)"),
+    },
+    async ({ port, timeout }) => {
+      const ready = await bgWaitPort(port, timeout);
+      return { content: [{ type: "text" as const, text: JSON.stringify({ port, ready }) }] };
+    }
+  );
+
+  // ── port_check ──────────────────────────────────────────────────────────
+
+  server.tool(
+    "port_check",
+    "Check if a port is in use and what process is using it.",
+    {
+      port: z.number().describe("Port number to check"),
+    },
+    async ({ port }) => {
+      const result = await h.exec(`lsof -i :${port} -P -n 2>/dev/null | head -5`, undefined, 5000);
+      const output = result.stdout.trim();
+      if (!output || result.exitCode !== 0) {
+        return { content: [{ type: "text" as const, text: JSON.stringify({ port, inUse: false }) }] };
+      }
+      const lines = output.split("\n").filter(l => l.trim());
+      return { content: [{ type: "text" as const, text: JSON.stringify({ port, inUse: true, processes: lines.slice(1).map(l => l.split(/\s+/).slice(0, 3).join(" ")) }) }] };
+    }
+  );
+}