agent-enderun 1.1.9 → 1.1.10

package/framework-mcp/dist/tools/memory/read_memory.js

@@ -1,28 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { resolveFrameworkDir } from "../../utils/security.js";
-/**
- * Reads the project's central memory (PROJECT_MEMORY.md).
- * This is the "brain" of the project.
- */
-export function handleReadProjectMemory(projectRoot, _args) {
-    try {
-        const frameworkDir = resolveFrameworkDir(projectRoot);
-        const memoryPath = path.join(projectRoot, frameworkDir, "memory/PROJECT_MEMORY.md");
-        if (!fs.existsSync(memoryPath)) {
-            return {
-                content: [{ type: "text", text: "ℹ️ Project memory file not found. It might be a new project." }]
-            };
-        }
-        const content = fs.readFileSync(memoryPath, "utf8");
-        return {
-            content: [{ type: "text", text: content }]
-        };
-    }
-    catch (e) {
-        return {
-            isError: true,
-            content: [{ type: "text", text: `Failed to read project memory: ${String(e)}` }]
-        };
-    }
-}

package/framework-mcp/dist/tools/messaging/log_action.js

@@ -1,22 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { resolveFrameworkDir } from "../../utils/security.js";
-export function handleLogAgentAction(projectRoot, args) {
-    const { agent, action, traceId, status, summary } = args;
-    const findings = args.findings ? args.findings.split(",").map(f => f.trim()) : [];
-    const frameworkDir = resolveFrameworkDir(projectRoot);
-    const agentName = agent.replace("@", "");
-    const logPath = path.join(projectRoot, frameworkDir, "logs", `${agentName}.json`);
-    const logEntry = {
-        timestamp: new Date().toISOString(),
-        agent,
-        action,
-        requestId: traceId,
-        status,
-        summary,
-        findings
-    };
-    fs.mkdirSync(path.dirname(logPath), { recursive: true });
-    fs.appendFileSync(logPath, JSON.stringify(logEntry) + "\n");
-    return { content: [{ type: "text", text: `✅ Action logged for ${agent} to ${path.join(frameworkDir, "logs", `${agentName}.json`)}` }] };
-}

package/framework-mcp/dist/tools/messaging/send_message.js

@@ -1,74 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { resolveFrameworkDir } from "../../utils/security.js";
-export async function handleSendAgentMessage(projectRoot, args) {
-    const { to, category, content, traceId } = args;
-    const from = args.from || "@mcp";
-    const frameworkDir = resolveFrameworkDir(projectRoot);
-    const messagesDir = path.join(projectRoot, frameworkDir, "messages");
-    const agentName = to.replace("@", "");
-    const messagePath = path.join(messagesDir, `${agentName}.json`);
-    const lockPath = path.join(messagesDir, `${agentName}.lock`);
-    // Hermes Lock Protocol: Retry 3 times with 500ms delay
-    let retries = 3;
-    let acquired = false;
-    while (retries > 0) {
-        try {
-            if (fs.existsSync(lockPath)) {
-                try {
-                    const stats = fs.statSync(lockPath);
-                    if (Date.now() - stats.mtimeMs > 5000) {
-                        fs.unlinkSync(lockPath);
-                    }
-                }
-                catch {
-                    // ignore if concurrently unlinked
-                }
-            }
-            fs.mkdirSync(messagesDir, { recursive: true });
-            fs.writeFileSync(lockPath, `Locked by ${from} at ${new Date().toISOString()}`, { flag: "wx" });
-            acquired = true;
-            break;
-        }
-        catch (err) {
-            const error = err;
-            if (error.code === "EEXIST") {
-                retries--;
-                if (retries > 0) {
-                    await new Promise((resolve) => setTimeout(resolve, 500));
-                }
-            }
-            else {
-                return { content: [{ type: "text", text: `❌ Unexpected lock acquisition error: ${error.message || String(err)}` }], isError: true };
-            }
-        }
-    }
-    if (!acquired) {
-        return { content: [{ type: "text", text: `❌ Could not send message to ${to}: Hermes lock is busy.` }], isError: true };
-    }
-    try {
-        const defaultPriority = (category === "ALERT" || category === "ACTION") ? "HIGH" : "NORMAL";
-        const message = {
-            timestamp: new Date().toISOString(),
-            from,
-            to,
-            category,
-            traceId,
-            content,
-            priority: args.priority || defaultPriority,
-            status: "PENDING"
-        };
-        fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
-        return { content: [{ type: "text", text: `✅ Message sent to ${to} (from: ${from})` }] };
-    }
-    finally {
-        if (acquired && fs.existsSync(lockPath)) {
-            try {
-                fs.unlinkSync(lockPath);
-            }
-            catch {
-                // ignore
-            }
-        }
-    }
-}

package/framework-mcp/dist/tools/observability/check_ports.js

@@ -1,26 +0,0 @@
-import { execSync } from "child_process";
-/**
- * Checks for active network ports and their status.
- */
-export function handleCheckPorts(projectRoot, args) {
-    const filter = args.filter || ""; // Optional filter (e.g., ":3000")
-    try {
-        // Using 'lsof -i -P -n' to list open files and network connections
-        // Note: may require permissions or behave differently on non-Unix systems
-        const command = process.platform === "win32"
-            ? `netstat -ano | findstr LISTENING ${filter ? `| findstr ${filter}` : ""}`
-            : `lsof -i -P -n | grep LISTEN ${filter ? `| grep ${filter}` : ""}`;
-        const output = execSync(command, { encoding: "utf8" });
-        return {
-            content: [{
-                    type: "text",
-                    text: `📡 **Active Listening Ports:**\n\n${output || "No active listening ports found matching filter."}`
-                }]
-        };
-    }
-    catch (_e) {
-        return {
-            content: [{ type: "text", text: "ℹ️ No active ports found or command failed (this is normal if nothing is listening)." }]
-        };
-    }
-}

package/framework-mcp/dist/tools/observability/get_health.js

@@ -1,19 +0,0 @@
-import os from "os";
-/**
- * Retrieves system health metrics including CPU load and memory usage.
- */
-export function handleGetSystemHealth(_projectRoot, _args) {
-    const totalMem = os.totalmem();
-    const freeMem = os.freemem();
-    const usedMem = totalMem - freeMem;
-    const memUsagePercent = ((usedMem / totalMem) * 100).toFixed(2);
-    const loadAvg = os.loadavg(); // [1, 5, 15] minute averages
-    const healthReport = `🖥️ **System Health Report**
-- **Memory:** ${memUsagePercent}% used (${(usedMem / 1024 / 1024 / 1024).toFixed(2)} GB / ${(totalMem / 1024 / 1024 / 1024).toFixed(2)} GB)
-- **CPU Load (1m, 5m, 15m):** ${loadAvg.map(l => l.toFixed(2)).join(", ")}
-- **Platform:** ${os.platform()} (${os.release()})
-- **Uptime:** ${(os.uptime() / 3600).toFixed(2)} hours`;
-    return {
-        content: [{ type: "text", text: healthReport }]
-    };
-}

package/framework-mcp/dist/tools/search/get_gaps.js

@@ -1,48 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { safePath } from "../../utils/security.js";
-/**
- * Scans the codebase for TODOs, FIXMEs, and empty function bodies.
- * Helps identify what's left and where the agent might have skipped logic.
- */
-export function handleGetProjectGaps(projectRoot, args) {
-    const srcDir = safePath(projectRoot, args.path || "src");
-    const results = [];
-    const walk = (dir) => {
-        if (!fs.existsSync(dir))
-            return;
-        const files = fs.readdirSync(dir);
-        for (const file of files) {
-            const fullPath = path.join(dir, file);
-            const relativePath = path.relative(projectRoot, fullPath);
-            if (fs.statSync(fullPath).isDirectory()) {
-                if (file !== "node_modules" && file !== "dist" && !file.startsWith(".")) {
-                    walk(fullPath);
-                }
-            }
-            else if (file.endsWith(".ts") || file.endsWith(".tsx")) {
-                const content = fs.readFileSync(fullPath, "utf8");
-                const lines = content.split("\n");
-                lines.forEach((line, index) => {
-                    // 1. Scan for markers
-                    if (line.includes("TODO") || line.includes("FIXME") || line.includes("!!!")) {
-                        results.push(`[${relativePath}:${index + 1}] Marker found: ${line.trim()}`);
-                    }
-                    // 2. Scan for empty function placeholders (heuristic)
-                    if (line.includes("throw new Error(\"Not implemented") || line.includes("// ... rest of code")) {
-                        results.push(`[${relativePath}:${index + 1}] Gap found: ${line.trim()}`);
-                    }
-                });
-            }
-        }
-    };
-    walk(srcDir);
-    return {
-        content: [{
-                type: "text",
-                text: results.length > 0
-                    ? `Found ${results.length} gaps/todos:\n\n${results.join("\n")}`
-                    : "✅ No major gaps or TODOs found in the scanned directory."
-            }]
-    };
-}

package/framework-mcp/dist/tools/search/get_map.js

@@ -1,43 +0,0 @@
-import fs from "fs";
-import path from "path";
-/**
- * Generates a tree-view map of the project structure.
- * Helps agents visualize the entire project layout quickly.
- */
-export function handleGetProjectMap(projectRoot, args) {
-    const maxDepth = Number(args.maxDepth) || 3;
-    const includeFiles = args.includeFiles !== false;
-    const buildTree = (dir, depth) => {
-        if (depth > maxDepth)
-            return [];
-        const results = [];
-        const files = fs.readdirSync(dir);
-        files.forEach(file => {
-            if (file === "node_modules" || file === ".git" || file === "dist" || file.startsWith("."))
-                return;
-            const fullPath = path.join(dir, file);
-            const stat = fs.statSync(fullPath);
-            const indent = "  ".repeat(depth);
-            if (stat.isDirectory()) {
-                results.push(`${indent}📁 ${file}/`);
-                results.push(...buildTree(fullPath, depth + 1));
-            }
-            else if (includeFiles) {
-                results.push(`${indent}📄 ${file}`);
-            }
-        });
-        return results;
-    };
-    try {
-        const tree = buildTree(projectRoot, 0);
-        return {
-            content: [{
-                    type: "text",
-                    text: `🗺️ **Project Map (Depth: ${maxDepth})**\n\n${tree.join("\n")}`
-                }]
-        };
-    }
-    catch (e) {
-        return { isError: true, content: [{ type: "text", text: `Failed to map project: ${String(e)}` }] };
-    }
-}

package/framework-mcp/dist/tools/search/grep_search.js

@@ -1,59 +0,0 @@
-import fs from "fs";
-import path from "path";
-/**
- * Searches for a regex pattern within files in the project.
- */
-export function handleGrepSearch(projectRoot, args) {
-    const pattern = args.pattern;
-    const includePattern = args.includePattern || ""; // e.g., ".ts"
-    const excludePattern = args.excludePattern || "node_modules";
-    if (!pattern) {
-        throw new Error("Search pattern is required.");
-    }
-    const results = [];
-    const regex = new RegExp(pattern, "g");
-    const walk = (dir) => {
-        const files = fs.readdirSync(dir);
-        for (const file of files) {
-            const fullPath = path.join(dir, file);
-            const relativePath = path.relative(projectRoot, fullPath);
-            // Skip excluded directories/files
-            if (relativePath.includes(excludePattern))
-                continue;
-            try {
-                const stat = fs.statSync(fullPath);
-                if (stat.isDirectory()) {
-                    walk(fullPath);
-                }
-                else if (stat.isFile()) {
-                    // Check include pattern
-                    if (includePattern && !file.endsWith(includePattern))
-                        continue;
-                    const content = fs.readFileSync(fullPath, "utf8");
-                    const lines = content.split("\n");
-                    lines.forEach((line, index) => {
-                        if (regex.test(line)) {
-                            results.push(`${relativePath}:${index + 1}: ${line.trim()}`);
-                            // Reset regex lastIndex because of 'g' flag
-                            regex.lastIndex = 0;
-                        }
-                    });
-                }
-            }
-            catch {
-                // Ignore read errors
-            }
-            if (results.length > 100)
-                break; // Limit results
-        }
-    };
-    walk(projectRoot);
-    return {
-        content: [{
-                type: "text",
-                text: results.length > 0
-                    ? `Found ${results.length} matches:\n\n${results.join("\n")}`
-                    : "No matches found."
-            }]
-    };
-}

package/framework-mcp/dist/tools/search/list_dir.js

@@ -1,28 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { safePath } from "../../utils/security.js";
-/**
- * Lists the contents of a directory.
- */
-export function handleListDir(projectRoot, args) {
-    const dirPath = safePath(projectRoot, args.path || ".");
-    if (!fs.existsSync(dirPath)) {
-        throw new Error(`Directory not found: ${args.path}`);
-    }
-    const stats = fs.statSync(dirPath);
-    if (!stats.isDirectory()) {
-        throw new Error(`Path is not a directory: ${args.path}`);
-    }
-    const files = fs.readdirSync(dirPath);
-    const results = files.map(file => {
-        const fullPath = path.join(dirPath, file);
-        const isDir = fs.statSync(fullPath).isDirectory();
-        return `${isDir ? "[DIR] " : "      "}${file}`;
-    });
-    return {
-        content: [{
-                type: "text",
-                text: `Directory listing for ${args.path || "."}:\n\n${results.join("\n")}`
-            }]
-    };
-}

package/framework-mcp/dist/tools/types.js

@@ -1 +0,0 @@
-export {};

package/framework-mcp/dist/utils/cli.js

@@ -1,20 +0,0 @@
-import { execFileSync } from "child_process";
-/**
- * Executes a CLI command safely using execFileSync (no shell injection risk).
- * Captures stderr gracefully to prevent stream crashes.
- */
-export function safeExec(command, args, cwd, timeout) {
-    try {
-        return execFileSync(command, args, {
-            cwd,
-            encoding: "utf8",
-            timeout: timeout || 30000,
-            maxBuffer: 1024 * 1024,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-    }
-    catch (error) {
-        const err = error;
-        throw new Error(err.stderr || err.message || "Command execution failed", { cause: error });
-    }
-}

package/framework-mcp/dist/utils/compliance.js

@@ -1,29 +0,0 @@
-/**
- * Enterprise Compliance Guardrail
- * Checks content against corporate standards before allowing file mutations.
- */
-export function verifyCorporateCompliance(content, filePath) {
-    // 1. Zero Console Policy
-    if (content.includes("console.log(") || content.includes("console.warn(") || content.includes("console.error(")) {
-        if (!filePath.includes("logger.ts") && !filePath.includes("check.ts") && !filePath.includes("cli.ts")) {
-            throw new Error("❌ Corporate Compliance Breach: 'console.log/warn/error' usage is forbidden. " +
-                "Use the 'logger' system from '@/shared/logger' instead.");
-        }
-    }
-    // 2. No Explicit Any Policy
-    const anyRegex = /[:<]\s*any\b|\bas\s+any\b/g;
-    if (anyRegex.test(content)) {
-        if (!filePath.includes("definitions.ts") && !filePath.includes("types.ts")) {
-            throw new Error("❌ Corporate Compliance Breach: 'any' type is forbidden. " +
-                "Use 'unknown', 'generics', or proper interfaces for type safety.");
-        }
-    }
-    // 3. Hardcoded Secrets Guard (Simple heuristic)
-    const secretKeywords = [/API_KEY\s*=\s*['"][^'"]+['"]/i, /SECRET\s*=\s*['"][^'"]+['"]/i, /PASSWORD\s*=\s*['"][^'"]+['"]/i];
-    for (const regex of secretKeywords) {
-        if (regex.test(content) && !filePath.endsWith(".env.example")) {
-            throw new Error("❌ Corporate Compliance Breach: Hardcoded secrets detected. " +
-                "All sensitive data must be managed via '.env' files.");
-        }
-    }
-}

package/framework-mcp/dist/utils/metrics.js

@@ -1,38 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { resolveFrameworkDir } from "./security.js";
-export const Metrics = {
-    /**
-     * Estimates tokens based on character count (rough heuristic: 1 token ~= 4 chars).
-     */
-    estimateTokens: (text) => {
-        return Math.ceil(text.length / 4);
-    },
-    /**
-     * Logs the token usage and action to the observability metrics file.
-     */
-    logUsage: (projectRoot, agent, action, tokens) => {
-        const frameworkDir = resolveFrameworkDir(projectRoot);
-        const metricsPath = path.join(projectRoot, frameworkDir, "observability/metrics.json");
-        try {
-            const metricsDir = path.dirname(metricsPath);
-            if (!fs.existsSync(metricsDir))
-                fs.mkdirSync(metricsDir, { recursive: true });
-            let currentMetrics = [];
-            if (fs.existsSync(metricsPath)) {
-                currentMetrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
-            }
-            currentMetrics.push({
-                timestamp: new Date().toISOString(),
-                agent,
-                action,
-                estimatedTokens: tokens
-            });
-            // Keep only last 100 entries to save space
-            if (currentMetrics.length > 100)
-                currentMetrics.shift();
-            fs.writeFileSync(metricsPath, JSON.stringify(currentMetrics, null, 2));
-        }
-        catch { /* ignore: metrics should not block the main process */ }
-    }
-};

package/framework-mcp/dist/utils/security.js

@@ -1,57 +0,0 @@
-import path from "path";
-import fs from "fs";
-/**
- * Validates and resolves a user-provided path to prevent path traversal attacks.
- * Ensures the resolved path stays within the project root boundary.
- */
-export function safePath(projectRoot, userPath) {
-    const resolved = path.resolve(projectRoot, userPath);
-    const normalizedRoot = path.resolve(projectRoot);
-    if (!resolved.startsWith(normalizedRoot + path.sep) && resolved !== normalizedRoot) {
-        throw new Error(`Access denied: path "${userPath}" escapes project root.`);
-    }
-    return resolved;
-}
-/**
- * Resolves the active framework directory.
- * Priority: package.json `enderun.frameworkDir` → `.enderun` → adapter dirs.
- * This ensures the canonical framework directory is always used,
- * even when adapter-specific dirs (e.g. `.gemini`) exist alongside it.
- */
-export function resolveFrameworkDir(projectRoot) {
-    // 1. Authoritative source: read from package.json if present
-    try {
-        const pkgPath = path.join(projectRoot, "package.json");
-        if (fs.existsSync(pkgPath)) {
-            const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-            const enderunConfig = pkg["enderun"];
-            if (enderunConfig && typeof enderunConfig["frameworkDir"] === "string") {
-                return enderunConfig["frameworkDir"];
-            }
-        }
-    }
-    catch {
-        // ignore — fall through to filesystem scan
-    }
-    // 2. Filesystem scan
-    const candidates = [
-        ".enderun",
-        ".cursor",
-        ".claude",
-        ".github",
-        ".grok",
-        ".windsurf",
-        ".antigravity",
-        ".agent",
-        ".gemini/antigravity-cli",
-        ".gemini",
-        ".agents",
-    ];
-    for (const candidate of candidates) {
-        const candidatePath = path.join(projectRoot, candidate);
-        if (fs.existsSync(candidatePath)) {
-            return candidate;
-        }
-    }
-    return ".gemini";
-}

package/framework-mcp/package.json

@@ -1,19 +0,0 @@
-{
-  "name": "@agent-enderun/mcp",
-  "version": "1.1.9",
-  "description": "Agent Enderun Model Context Protocol (MCP) Server",
-  "type": "module",
-  "scripts": {
-    "build": "npx tsc",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "zod": "^3.24.2"
-  },
-  "devDependencies": {
-    "@types/node": "^25.9.1",
-    "typescript": "^6.0.3"
-  }
-}

package/framework-mcp/src/declarations.d.ts

@@ -1,17 +0,0 @@
-declare module "@modelcontextprotocol/sdk/server/index.js" {
-    export class Server {
-        constructor(info: { name: string; version: string }, options: { capabilities: { tools: Record<string, never> } });
-        setRequestHandler(schema: unknown, handler: (request: unknown) => Promise<unknown>): void;
-        connect(transport: unknown): Promise<void>;
-        close(): Promise<void>;
-    }
-}
-
-declare module "@modelcontextprotocol/sdk/server/stdio.js" {
-    export class StdioServerTransport {}
-}
-
-declare module "@modelcontextprotocol/sdk/types.js" {
-    export const ListToolsRequestSchema: unknown;
-    export const CallToolRequestSchema: unknown;
-}

package/framework-mcp/src/index.ts

@@ -1,95 +0,0 @@
-import fs from "fs";
-import path from "path";
-import { fileURLToPath } from "url";
-import { Server } from "@modelcontextprotocol/sdk/server/index.js";
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import {
-    CallToolRequestSchema,
-    ListToolsRequestSchema,
-} from "@modelcontextprotocol/sdk/types.js";
-
-import { CallToolRequest } from "./tools/types.js";
-import { TOOLS, toolHandlers } from "./tools/index.js";
-
-
-// ─── Server Setup ─────────────────────────────────────────────────
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(fs.readFileSync(path.join(__dirname, "../package.json"), "utf8"));
-const serverVersion = pkg.version || "1.1.5";
-
-const server = new Server(
-    {
-        name: "@agent-enderun/mcp",
-        version: serverVersion,
-    },
-    {
-        capabilities: {
-            tools: {},
-        },
-    }
-);
-
-server.setRequestHandler(ListToolsRequestSchema, async () => {
-    return { tools: TOOLS };
-});
-
-server.setRequestHandler(CallToolRequestSchema, async (request) => {
-    const typedRequest = request as CallToolRequest;
-    const { name, arguments: args } = typedRequest.params;
-    const projectRoot = process.env.ENDERUN_PROJECT_ROOT || process.cwd();
-
-    try {
-        const handler = toolHandlers[name];
-        if (!handler) {
-            return {
-                isError: true,
-                content: [{ type: "text" as const, text: `Unknown tool: ${name}` }],
-            };
-        }
-        return handler(projectRoot, args || {});
-    } catch (error: unknown) {
-        const message = error instanceof Error ? error.message : "Unknown error occurred";
-        return {
-            isError: true,
-            content: [{ type: "text" as const, text: message }],
-        };
-    }
-});
-
-// ─── Graceful Startup & Shutdown ──────────────────────────────────
-
-async function run() {
-    const transport = new StdioServerTransport();
-
-    // Prevent unhandled errors from crashing the MCP stream
-    process.on("uncaughtException", (error: Error) => {
-        process.stderr.write(`[agent-enderun-mcp] Uncaught exception: ${error.message}
-`);
-    });
-    process.on("unhandledRejection", (reason: unknown) => {
-        const message = reason instanceof Error ? reason.message : String(reason);
-        process.stderr.write(`[agent-enderun-mcp] Unhandled rejection: ${message}
-`);
-    });
-
-    // Graceful shutdown on SIGINT/SIGTERM
-    const shutdown = async () => {
-        try {
-            await server.close();
-        } catch {
-            // Already closed or failed — safe to ignore
-        }
-        process.exit(0);
-    };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-
-    await server.connect(transport);
-}
-
-run().catch((error: Error) => {
-    process.stderr.write(`[agent-enderun-mcp] Fatal startup error: ${error.message}
-`);
-    process.exit(1);
-});