@hasna/terminal 4.3.1 → 4.3.2

package/dist/mcp/tools/git.js

@@ -0,0 +1,233 @@
+// Git tools: commit, bulk_commit, smart_commit, diff, repo_state, last_commit
+import { z } from "./helpers.js";
+import { stripAnsi } from "../../compression.js";
+import { estimateTokens } from "../../tokens.js";
+import { processOutput } from "../../output-processor.js";
+import { getOutputProvider } from "../../providers/index.js";
+import { invalidateBootCache } from "../../session-boot.js";
+export function registerGitTools(server, h) {
+    // ── commit ────────────────────────────────────────────────────────────────
+    server.tool("commit", "Commit and optionally push. Agent says what to commit, we handle git add/commit/push. Saves ~400 tokens vs raw git commands.", {
+        message: z.string().describe("Commit message"),
+        files: z.array(z.string()).optional().describe("Files to stage (default: all changed)"),
+        push: z.boolean().optional().describe("Push after commit (default: false)"),
+        cwd: z.string().optional().describe("Working directory"),
+    }, async ({ message, files, push, cwd }) => {
+        const start = Date.now();
+        const workDir = cwd ?? process.cwd();
+        const addCmd = files && files.length > 0 ? `git add ${files.map(f => `"${f}"`).join(" ")}` : "git add -A";
+        const commitCmd = `${addCmd} && git commit -m ${JSON.stringify(message)}`;
+        const fullCmd = push ? `${commitCmd} && git push` : commitCmd;
+        const result = await h.exec(fullCmd, workDir, 30000);
+        const output = (result.stdout + result.stderr).trim();
+        h.logCall("commit", { command: `commit: ${message.slice(0, 80)}`, durationMs: Date.now() - start, exitCode: result.exitCode });
+        invalidateBootCache();
+        return { content: [{ type: "text", text: JSON.stringify({
+                        exitCode: result.exitCode,
+                        output: stripAnsi(output).split("\n").filter(l => l.trim()).slice(0, 5).join("\n"),
+                        pushed: push ?? false,
+                    }) }] };
+    });
+    // ── bulk_commit ───────────────────────────────────────────────────────────
+    server.tool("bulk_commit", "Multiple logical commits in one call. Agent decides which files go in which commit, we handle all git commands. No AI cost. Use smart_commit instead if you want AI to decide the grouping.", {
+        commits: z.array(z.object({
+            message: z.string().describe("Commit message"),
+            files: z.array(z.string()).describe("Files to stage for this commit"),
+        })).describe("Array of logical commits"),
+        push: z.boolean().optional().describe("Push after all commits (default: true)"),
+        cwd: z.string().optional().describe("Working directory"),
+    }, async ({ commits, push, cwd }) => {
+        const start = Date.now();
+        const workDir = cwd ?? process.cwd();
+        const results = [];
+        for (const c of commits) {
+            const fileArgs = c.files.map(f => `"${f}"`).join(" ");
+            const cmd = `git add ${fileArgs} && git commit -m ${JSON.stringify(c.message)}`;
+            const r = await h.exec(cmd, workDir, 15000);
+            results.push({ message: c.message, files: c.files.length, ok: r.exitCode === 0 });
+        }
+        let pushed = false;
+        if (push !== false) {
+            const pushResult = await h.exec("git push", workDir, 30000);
+            pushed = pushResult.exitCode === 0;
+        }
+        invalidateBootCache();
+        h.logCall("bulk_commit", { command: `${commits.length} commits`, durationMs: Date.now() - start });
+        return { content: [{ type: "text", text: JSON.stringify({ commits: results, pushed, total: results.length }) }] };
+    });
+    // ── smart_commit ──────────────────────────────────────────────────────────
+    server.tool("smart_commit", "AI-powered git commit. Analyzes all changes, groups into logical commits with generated messages, stages and commits each group, optionally pushes. One call replaces the entire git workflow. Agent just says 'commit my work'.", {
+        push: z.boolean().optional().describe("Push after all commits (default: true)"),
+        hint: z.string().optional().describe("Optional context about the changes (e.g., 'fixed auth + added users endpoint')"),
+        cwd: z.string().optional().describe("Working directory"),
+    }, async ({ push, hint, cwd }) => {
+        const start = Date.now();
+        const workDir = cwd ?? process.cwd();
+        // 1. Get all changed files
+        const status = await h.exec("git status --porcelain", workDir, 10000);
+        const diffStat = await h.exec("git diff --stat", workDir, 10000);
+        const untrackedDiff = await h.exec("git diff HEAD --stat", workDir, 10000);
+        const changedFiles = status.stdout.trim();
+        if (!changedFiles) {
+            return { content: [{ type: "text", text: JSON.stringify({ message: "Nothing to commit — working tree clean" }) }] };
+        }
+        // 2. AI groups changes into logical commits
+        const provider = getOutputProvider();
+        const outputModel = provider.name === "groq" ? "llama-3.1-8b-instant" : undefined;
+        const grouping = await provider.complete(`Changed files:\n${changedFiles}\n\nDiff stats:\n${diffStat.stdout}\n${untrackedDiff.stdout}${hint ? `\n\nContext: ${hint}` : ""}`, {
+            model: outputModel,
+            system: `You are a git commit assistant. Group these changed files into logical commits. Return ONLY a JSON array:
+
+[{"message": "conventional commit message", "files": ["file1.ts", "file2.ts"]}]
+
+Rules:
+- Group related changes (same feature, same fix, same refactor)
+- Use conventional commits: feat:, fix:, refactor:, test:, docs:, chore:
+- Message should explain WHY, not WHAT (the diff shows what)
+- Each file appears in exactly one group
+- If all changes are related, use a single commit
+- Extract file paths from the status output (skip the status prefix like M, A, ??)`,
+            maxTokens: 1000,
+            temperature: 0,
+        });
+        let commits = [];
+        try {
+            const jsonMatch = grouping.match(/\[[\s\S]*\]/);
+            if (jsonMatch)
+                commits = JSON.parse(jsonMatch[0]);
+        }
+        catch { }
+        if (commits.length === 0) {
+            // Fallback: single commit with all files
+            commits = [{ message: hint ?? "chore: update files", files: changedFiles.split("\n").map(l => l.slice(3).trim()) }];
+        }
+        // 3. Execute each commit
+        const results = [];
+        for (const c of commits) {
+            const fileArgs = c.files.map(f => `"${f}"`).join(" ");
+            const cmd = `git add ${fileArgs} && git commit -m ${JSON.stringify(c.message)}`;
+            const r = await h.exec(cmd, workDir, 15000);
+            results.push({ message: c.message, files: c.files.length, ok: r.exitCode === 0 });
+        }
+        // 4. Push if requested
+        let pushed = false;
+        if (push !== false) {
+            const pushResult = await h.exec("git push", workDir, 30000);
+            pushed = pushResult.exitCode === 0;
+        }
+        invalidateBootCache();
+        h.logCall("smart_commit", { command: `${commits.length} commits`, durationMs: Date.now() - start, aiProcessed: true });
+        return { content: [{ type: "text", text: JSON.stringify({
+                        commits: results,
+                        pushed,
+                        total: results.length,
+                        ok: results.every(r => r.ok),
+                    }) }] };
+    });
+    // ── diff ──────────────────────────────────────────────────────────────────
+    server.tool("diff", "Show what changed — git diff with AI summary. One call replaces constructing git diff commands.", {
+        ref: z.string().optional().describe("Diff against this ref (default: unstaged changes). Examples: HEAD~1, main, abc123"),
+        file: z.string().optional().describe("Diff a specific file only"),
+        stat: z.boolean().optional().describe("Show file-level stats only, not full diff (default: false)"),
+        cwd: z.string().optional().describe("Working directory"),
+    }, async ({ ref, file, stat, cwd }) => {
+        const start = Date.now();
+        const workDir = cwd ?? process.cwd();
+        let cmd = "git diff";
+        if (ref)
+            cmd += ` ${ref}`;
+        if (stat)
+            cmd += " --stat";
+        if (file)
+            cmd += ` -- ${file}`;
+        const result = await h.exec(cmd, workDir, 15000);
+        const output = (result.stdout + result.stderr).trim();
+        if (!output) {
+            return { content: [{ type: "text", text: JSON.stringify({ clean: true, message: "No changes" }) }] };
+        }
+        const processed = await processOutput(cmd, output);
+        h.logCall("diff", { command: cmd, outputTokens: estimateTokens(output), tokensSaved: processed.tokensSaved, durationMs: Date.now() - start, aiProcessed: processed.aiProcessed });
+        return { content: [{ type: "text", text: JSON.stringify({
+                        summary: processed.summary,
+                        lines: output.split("\n").length,
+                        tokensSaved: processed.tokensSaved,
+                    }) }] };
+    });
+    // ── repo_state ────────────────────────────────────────────────────────────
+    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([
+            h.exec("git status --porcelain", cwd),
+            h.exec("git diff --stat", cwd),
+            h.exec("git log --oneline -12 --decorate", cwd),
+        ]);
+        const branchResult = await h.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,
+                    }) }],
+        };
+    });
+    // ── last_commit ───────────────────────────────────────────────────────────
+    server.tool("last_commit", "Get details of the last commit — hash, message, files changed, diff stats. Replaces: git log -1 + git show --stat + git diff HEAD~1.", {
+        path: z.string().optional().describe("Repo path (default: cwd)"),
+    }, async ({ path }) => {
+        const cwd = path ?? process.cwd();
+        const [logResult, statResult] = await Promise.all([
+            h.exec("git log -1 --format='%H%n%s%n%an%n%ai'", cwd),
+            h.exec("git show --stat --format='' HEAD", cwd),
+        ]);
+        const [hash, message, author, date] = logResult.stdout.split("\n");
+        const filesChanged = statResult.stdout.split("\n").filter(l => l.trim() && !l.includes("changed"));
+        return {
+            content: [{ type: "text", text: JSON.stringify({
+                        hash: hash?.trim(),
+                        message: message?.trim(),
+                        author: author?.trim(),
+                        date: date?.trim(),
+                        filesChanged,
+                    }) }],
+        };
+    });
+    // ── git_init ────────────────────────────────────────────────────────────
+    server.tool("git_init", "Initialize a new git repo, optionally with .gitignore and initial commit.", {
+        cwd: z.string().optional().describe("Directory to init (default: cwd)"),
+        gitignore: z.string().optional().describe("Content for .gitignore file"),
+        initialCommit: z.boolean().optional().describe("Create initial commit (default: true)"),
+    }, async ({ cwd, gitignore, initialCommit }) => {
+        const workDir = cwd ?? process.cwd();
+        await h.exec("git init", workDir, 5000);
+        if (gitignore) {
+            const { writeFileSync } = await import("fs");
+            const { join } = await import("path");
+            writeFileSync(join(workDir, ".gitignore"), gitignore);
+        }
+        if (initialCommit !== false) {
+            await h.exec("git add -A && git commit -m 'init' --allow-empty", workDir, 10000);
+        }
+        h.logCall("git_init", { command: "git init" });
+        return { content: [{ type: "text", text: JSON.stringify({ initialized: true, cwd: workDir }) }] };
+    });
+}

package/dist/mcp/tools/helpers.js

@@ -0,0 +1,63 @@
+// Shared helpers for all MCP tools
+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";
+/** Create shared helpers for tool modules */
+export function createHelpers(sessionId) {
+    function exec(command, cwd, timeout, allowRewrite = false) {
+        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) => { stdout += d.toString(); });
+            proc.stderr?.on("data", (d) => { 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, cwd) {
+        if (!p)
+            return cwd ?? process.cwd();
+        if (p.startsWith("/") || p.startsWith("~"))
+            return p;
+        return join(cwd ?? process.cwd(), p);
+    }
+    function logCall(tool, data) {
+        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/dist/mcp/tools/memory.js

@@ -0,0 +1,151 @@
+// Memory tools: remember, recall, project_note, store_secret, list_secrets
+import { z } from "./helpers.js";
+// Fallback memory store when mementos SDK not available
+function getLocalMemoryFile() {
+    const { join } = require("path");
+    return join(process.cwd(), ".terminal", "memories.json");
+}
+function loadLocalMemories() {
+    const { existsSync, readFileSync } = require("fs");
+    const file = getLocalMemoryFile();
+    if (!existsSync(file))
+        return [];
+    try {
+        return JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return [];
+    }
+}
+function saveLocalMemory(key, value, importance) {
+    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, h) {
+    // ── 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", 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 = [];
+        // 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) => ({ 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", 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 = [];
+        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", 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", text: JSON.stringify({ saved: true, total: notes.length }) }] };
+        }
+        return { content: [{ type: "text", 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 = {};
+        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", 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 = [];
+        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", text: JSON.stringify({ stored: names, environment: envSecrets }) }] };
+    });
+}

package/dist/mcp/tools/meta.js

@@ -0,0 +1,138 @@
+// Meta tools: token_stats, session_history, snapshot, watch, list_recipes, run_recipe, save_recipe, list_collections
+import { z } from "./helpers.js";
+import { stripAnsi } from "../../compression.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, h) {
+    // ── 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", 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", text: JSON.stringify(getSessionStats()) }] };
+        }
+        if (action === "detail" && sessionId) {
+            const interactions = getSessionInteractions(sessionId);
+            const economy = getSessionEconomy(sessionId);
+            return { content: [{ type: "text", text: JSON.stringify({ interactions, economy }) }] };
+        }
+        const sessions = listSessions(limit ?? 20);
+        return { content: [{ type: "text", 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", 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", 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", 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", 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", 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", 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", 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", text: JSON.stringify(collections) }] };
+    });
+}

package/dist/mcp/tools/process.js

@@ -0,0 +1,50 @@
+// Process tools: bg_start, bg_stop, bg_status, bg_logs, bg_wait_port
+import { z } from "./helpers.js";
+import { bgStart, bgStatus, bgStop, bgLogs, bgWaitPort } from "../../supervisor.js";
+export function registerProcessTools(server, h) {
+    // ── 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", 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", 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", 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", 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", 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", text: JSON.stringify({ port, inUse: false }) }] };
+        }
+        const lines = output.split("\n").filter(l => l.trim());
+        return { content: [{ type: "text", text: JSON.stringify({ port, inUse: true, processes: lines.slice(1).map(l => l.split(/\s+/).slice(0, 3).join(" ")) }) }] };
+    });
+}