agent-enderun 0.9.4 → 0.9.5

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

@@ -0,0 +1,35 @@
+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 by scanning known candidates.
+ */
+export function resolveFrameworkDir(projectRoot) {
+    const candidates = [
+        ".gemini/antigravity",
+        ".gemini/antigravity-cli",
+        ".gemini",
+        ".claude",
+        ".grok",
+        ".agent",
+        ".enderun",
+    ];
+    for (const candidate of candidates) {
+        const candidatePath = path.join(projectRoot, candidate);
+        if (fs.existsSync(candidatePath)) {
+            return candidate;
+        }
+    }
+    return ".enderun";
+}

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

@@ -1,3 +1,17 @@
-declare module "@modelcontextprotocol/sdk/server/index.js";
-declare module "@modelcontextprotocol/sdk/server/stdio.js";
-declare module "@modelcontextprotocol/sdk/types.js";
+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

@@ -4,9 +4,12 @@ import {
     CallToolRequestSchema,
     ListToolsRequestSchema,
 } from "@modelcontextprotocol/sdk/types.js";
-import fs from "fs";
-import path from "path";
-import { execSync } from "child_process";
+
+import { CallToolRequest, ToolResult } from "./tools/types.js";
+import { TOOLS, toolHandlers } from "./tools/index.js";
+
+
+// ─── Server Setup ─────────────────────────────────────────────────
 
 const server = new Server(
     {
@@ -20,297 +23,66 @@ const server = new Server(
     }
 );
 
-const TOOLS: any[] = [
-    {
-        name: "read_file",
-        description: "Read the content of a file within the project.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the file relative to project root" },
-            },
-            required: ["path"],
-        },
-    },
-    {
-        name: "write_file",
-        description: "Write content to a file. Creates directories if missing.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the file relative to project root" },
-                content: { type: "string", description: "Complete content of the file" },
-            },
-            required: ["path", "content"],
-        },
-    },
-    {
-        name: "replace_text",
-        description: "Surgically replace a string in a file with another string.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the file" },
-                oldText: { type: "string", description: "The exact text to find" },
-                newText: { type: "string", description: "The text to replace it with" },
-            },
-            required: ["path", "oldText", "newText"],
-        },
-    },
-    {
-        name: "patch_file",
-        description: "Safely update a file by replacing a specific line range with new content.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                path: { type: "string", description: "Path to the file" },
-                startLine: { type: "number", description: "Starting line number (1-indexed)" },
-                endLine: { type: "number", description: "Ending line number (inclusive)" },
-                newContent: { type: "string", description: "The new lines to insert" },
-            },
-            required: ["path", "startLine", "endLine", "newContent"],
-        },
-    },
-    {
-        name: "get_framework_status",
-        description: "Get the current project phase, active traces, and agent states.",
-        inputSchema: { type: "object", properties: {} },
-    },
-    {
-        name: "update_project_memory",
-        description: "Update a specific section in PROJECT_MEMORY.md.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                section: { type: "string", description: "Section name (e.g., HISTORY, ACTIVE TASKS)" },
-                content: { type: "string", description: "Markdown content to append or set" },
-            },
-            required: ["section", "content"],
-        },
-    },
-    {
-        name: "orchestrate_loop",
-        description: "Process the pending Hermes messages and trigger dynamic state transitions.",
-        inputSchema: { type: "object", properties: {} },
-    },
-    {
-        name: "send_agent_message",
-        description: "Send a Hermes protocol message to another agent.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                to: { type: "string", description: "Target agent (e.g., @backend, @qa)" },
-                category: { type: "string", enum: ["ACTION", "DELEGATION", "INFO", "ALERT"] },
-                content: { type: "string", description: "Message content" },
-                traceId: { type: "string", description: "Active Trace ID" },
-            },
-            required: ["to", "category", "content", "traceId"],
-        },
-    },
-    {
-        name: "log_agent_action",
-        description: "Log an agent action to the framework logs.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                agent: { type: "string", description: "The agent name (e.g., @manager, @backend)" },
-                action: { type: "string", description: "Action type or name" },
-                traceId: { type: "string", description: "The active Trace ID" },
-                status: { type: "string", enum: ["SUCCESS", "FAILURE"], description: "The status of the action" },
-                summary: { type: "string", description: "Brief description of the action taken" },
-                findings: { type: "array", items: { type: "string" }, description: "Optional findings or details" }
-            },
-            required: ["agent", "action", "traceId", "status", "summary"]
-        }
-    },
-    {
-        name: "update_contract_hash",
-        description: "Re-generate and synchronize the backend contract SHA-256 hash.",
-        inputSchema: { type: "object", properties: {} }
-    }
-];
-
-server.onRequest(ListToolsRequestSchema, async () => {
+server.setRequestHandler(ListToolsRequestSchema, async () => {
     return { tools: TOOLS };
 });
 
-server.onRequest(CallToolRequestSchema, async (request: any) => {
-    const { name, arguments: args } = request.params as { name: string, arguments?: Record<string, unknown> };
-
-    const projectRoot = process.cwd();
+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 {
-        switch (name) {
-        case "read_file": {
-            const filePath = path.join(projectRoot, args?.path as string);
-            const content = fs.readFileSync(filePath, "utf8");
-            return { content: [{ type: "text", text: content }] };
-        }
-
-        case "write_file": {
-            const filePath = path.join(projectRoot, args?.path as string);
-            fs.mkdirSync(path.dirname(filePath), { recursive: true });
-            fs.writeFileSync(filePath, args?.content as string);
-            return { content: [{ type: "text", text: `✅ File written: ${args?.path}` }] };
-        }
-
-        case "replace_text": {
-            const filePath = path.join(projectRoot, args?.path as string);
-            let content = fs.readFileSync(filePath, "utf8");
-            const oldText = args?.oldText as string;
-            const newText = args?.newText as string;
-        
-            if (!content.includes(oldText)) {
-                throw new Error(`Text not found in file: ${oldText}`);
-            }
-        
-            content = content.replace(oldText, newText);
-            fs.writeFileSync(filePath, content);
-            return { content: [{ type: "text", text: `✅ Surgical edit successful in ${args?.path}` }] };
-        }
-
-        case "patch_file": {
-            const filePath = path.join(projectRoot, args?.path as string);
-            const lines = fs.readFileSync(filePath, "utf8").split("\n");
-            const start = (args?.startLine as number) - 1;
-            const end = (args?.endLine as number);
-            const newContent = (args?.newContent as string).split("\n");
-
-            if (start < 0 || start > lines.length) throw new Error("Invalid start line.");
-        
-            lines.splice(start, end - start, ...newContent);
-            fs.writeFileSync(filePath, lines.join("\n"));
-            return { content: [{ type: "text", text: `✅ File patched successfully: ${args?.path}` }] };
-        }
-
-        case "get_framework_status": {
-            const output = execSync("npx agent-enderun status").toString();
-            return { content: [{ type: "text", text: output }] };
-        }
-
-        case "update_project_memory": {
-            const section = args?.section as string;
-            const content = args?.content as string;
-            // Escape quotes for shell
-            const safeContent = content.replace(/"/g, "\\\"");
-            execSync(`npx agent-enderun update_project_memory "${section}" "${safeContent}"`);
-            return { content: [{ type: "text", text: `✅ Section ${section} updated.` }] };
-        }
-
-        case "orchestrate_loop": {
-            const output = execSync("npx agent-enderun orchestrate").toString();
-            return { content: [{ type: "text", text: output }] };
-        }
-
-        case "send_agent_message": {
-            interface SendAgentMessageArgs {
-                to: string;
-                category: "ACTION" | "DELEGATION" | "INFO" | "ALERT";
-                content: string;
-                traceId: string;
-            }
-            const { to, category, content, traceId } = args as any as SendAgentMessageArgs;
-            const candidates = [
-                ".gemini/antigravity",
-                ".gemini/antigravity-cli",
-                ".gemini",
-                ".claude",
-                ".grok",
-                ".agent",
-                ".enderun",
-            ];
-            let frameworkDir = ".gemini";
-            for (const c of candidates) {
-                if (fs.existsSync(path.join(projectRoot, c))) {
-                    frameworkDir = c;
-                    break;
-                }
-            }
-            const messagePath = path.join(projectRoot, frameworkDir, "messages", `${to.replace("@", "")}.json`);
-        
-            const message = {
-                timestamp: new Date().toISOString(),
-                from: "@mcp",
-                to,
-                category,
-                traceId,
-                content,
-                status: "PENDING"
-            };
-
-            fs.mkdirSync(path.dirname(messagePath), { recursive: true });
-            fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
-        
-            return { content: [{ type: "text", text: `✅ Message sent to ${to}` }] };
-        }
-
-        case "log_agent_action": {
-            interface LogAgentActionArgs {
-                agent: string;
-                action: string;
-                traceId: string;
-                status: "SUCCESS" | "FAILURE";
-                summary: string;
-                findings?: string[];
-            }
-            const { agent, action, traceId, status, summary, findings } = args as any as LogAgentActionArgs;
-            
-            const candidates = [
-                ".gemini/antigravity",
-                ".gemini/antigravity-cli",
-                ".gemini",
-                ".claude",
-                ".grok",
-                ".agent",
-                ".enderun",
-            ];
-            let frameworkDir = ".enderun";
-            for (const c of candidates) {
-                if (fs.existsSync(path.join(projectRoot, c))) {
-                    frameworkDir = c;
-                    break;
-                }
-            }
-            
-            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: findings || []
+        const handler = toolHandlers[name];
+        if (!handler) {
+            return {
+                isError: true,
+                content: [{ type: "text" as const, text: `Unknown tool: ${name}` }],
             };
-            
-            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`)}` }] };
-        }
-
-        case "update_contract_hash": {
-            const output = execSync("npx agent-enderun update-contract").toString();
-            return { content: [{ type: "text", text: output }] };
-        }
-
-        default:
-            throw new Error(`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", text: message }],
+            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(console.error);
+run().catch((error: Error) => {
+    process.stderr.write(`[agent-enderun-mcp] Fatal startup error: ${error.message}
+`);
+    process.exit(1);
+});

package/framework-mcp/src/tools/definitions.ts

@@ -0,0 +1,111 @@
+import { ToolDefinition } from "../tools/types.js";
+
+export const TOOLS: ToolDefinition[] = [
+    {
+        name: "read_file",
+        description: "Read the content of a file within the project.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file relative to project root" },
+            },
+            required: ["path"],
+        },
+    },
+    {
+        name: "write_file",
+        description: "Write content to a file. Creates directories if missing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file relative to project root" },
+                content: { type: "string", description: "Complete content of the file" },
+            },
+            required: ["path", "content"],
+        },
+    },
+    {
+        name: "replace_text",
+        description: "Surgically replace a string in a file with another string.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file" },
+                oldText: { type: "string", description: "The exact text to find" },
+                newText: { type: "string", description: "The text to replace it with" },
+            },
+            required: ["path", "oldText", "newText"],
+        },
+    },
+    {
+        name: "patch_file",
+        description: "Safely update a file by replacing a specific line range with new content.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file" },
+                startLine: { type: "number", description: "Starting line number (1-indexed)" },
+                endLine: { type: "number", description: "Ending line number (inclusive)" },
+                newContent: { type: "string", description: "The new lines to insert" },
+            },
+            required: ["path", "startLine", "endLine", "newContent"],
+        },
+    },
+    {
+        name: "get_framework_status",
+        description: "Get the current project phase, active traces, and agent states.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "update_project_memory",
+        description: "Update a specific section in PROJECT_MEMORY.md.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                section: { type: "string", description: "Section name (e.g., HISTORY, ACTIVE TASKS)" },
+                content: { type: "string", description: "Markdown content to append or set" },
+            },
+            required: ["section", "content"],
+        },
+    },
+    {
+        name: "orchestrate_loop",
+        description: "Process the pending Hermes messages and trigger dynamic state transitions.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "send_agent_message",
+        description: "Send a Hermes protocol message to another agent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                to: { type: "string", description: "Target agent (e.g., @backend, @qa)" },
+                category: { type: "string", enum: ["ACTION", "DELEGATION", "INFO", "ALERT"] },
+                content: { type: "string", description: "Message content" },
+                traceId: { type: "string", description: "Active Trace ID" },
+            },
+            required: ["to", "category", "content", "traceId"],
+        },
+    },
+    {
+        name: "log_agent_action",
+        description: "Log an agent action to the framework logs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent: { type: "string", description: "The agent name (e.g., @manager, @backend)" },
+                action: { type: "string", description: "Action type or name" },
+                traceId: { type: "string", description: "The active Trace ID" },
+                status: { type: "string", enum: ["SUCCESS", "FAILURE"], description: "The status of the action" },
+                summary: { type: "string", description: "Brief description of the action taken" },
+                findings: { type: "string", description: "Optional comma-separated findings or details" }
+            },
+            required: ["agent", "action", "traceId", "status", "summary"]
+        }
+    },
+    {
+        name: "update_contract_hash",
+        description: "Re-generate and synchronize the backend contract SHA-256 hash.",
+        inputSchema: { type: "object", properties: {} }
+    }
+];

package/framework-mcp/src/tools/file_system/patch_file.ts

@@ -0,0 +1,23 @@
+import fs from "fs";
+import { safePath } from "../../utils/security.js";
+import { ToolArgs, ToolResult } from "../types.js";
+
+export function handlePatchFile(projectRoot: string, args: ToolArgs): ToolResult {
+    const filePath = safePath(projectRoot, args.path as string);
+    const lines = fs.readFileSync(filePath, "utf8").split("\n");
+    const start = (args.startLine as number) - 1;
+    const end = args.endLine as number;
+    const newContent = (args.newContent as string).split("\n");
+
+    if (start < 0 || start > lines.length) {
+        throw new Error(`Invalid start line: ${start + 1}. File has ${lines.length} lines.`);
+    }
+    if (end < start + 1 || end > lines.length) {
+        throw new Error(`Invalid end line: ${end}. Must be between ${start + 1} and ${lines.length}.`);
+    }
+
+    lines.splice(start, end - start, ...newContent);
+    fs.writeFileSync(filePath, lines.join("\n"));
+    return { content: [{ type: "text", text: `✅ File patched successfully: ${args.path}` }] };
+}
+

package/framework-mcp/src/tools/file_system/read_file.ts

@@ -0,0 +1,9 @@
+import fs from "fs";
+import { safePath } from "../../utils/security.js";
+import { ToolArgs, ToolResult } from "../types.js";
+
+export function handleReadFile(projectRoot: string, args: ToolArgs): ToolResult {
+    const filePath = safePath(projectRoot, args.path as string);
+    const content = fs.readFileSync(filePath, "utf8");
+    return { content: [{ type: "text", text: content }] };
+}

package/framework-mcp/src/tools/file_system/replace_text.ts

@@ -0,0 +1,18 @@
+import fs from "fs";
+import { safePath } from "../../utils/security.js";
+import { ToolArgs, ToolResult } from "../types.js";
+
+export function handleReplaceText(projectRoot: string, args: ToolArgs): ToolResult {
+    const filePath = safePath(projectRoot, args.path as string);
+    let content = fs.readFileSync(filePath, "utf8");
+    const oldText = args.oldText as string;
+    const newText = args.newText as string;
+
+    if (!content.includes(oldText)) {
+        throw new Error(`Text not found in file: ${oldText.slice(0, 100)}...`);
+    }
+
+    content = content.replace(oldText, newText);
+    fs.writeFileSync(filePath, content);
+    return { content: [{ type: "text", text: `✅ Surgical edit successful in ${args.path}` }] };
+}

package/framework-mcp/src/tools/file_system/write_file.ts

@@ -0,0 +1,11 @@
+import fs from "fs";
+import path from "path";
+import { safePath } from "../../utils/security.js";
+import { ToolArgs, ToolResult } from "../types.js";
+
+export function handleWriteFile(projectRoot: string, args: ToolArgs): ToolResult {
+    const filePath = safePath(projectRoot, args.path as string);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, args.content as string);
+    return { content: [{ type: "text", text: `✅ File written: ${args.path}` }] };
+}

package/framework-mcp/src/tools/framework/get_status.ts

@@ -0,0 +1,7 @@
+import { safeExec } from "../../utils/cli.js";
+import { ToolResult } from "../types.js";
+
+export function handleGetFrameworkStatus(projectRoot: string): ToolResult {
+    const output = safeExec("npx", ["agent-enderun", "status"], projectRoot);
+    return { content: [{ type: "text", text: output }] };
+}

package/framework-mcp/src/tools/framework/orchestrate.ts

@@ -0,0 +1,7 @@
+import { safeExec } from "../../utils/cli.js";
+import { ToolResult } from "../types.js";
+
+export function handleOrchestrateLoop(projectRoot: string): ToolResult {
+    const output = safeExec("npx", ["agent-enderun", "orchestrate"], projectRoot);
+    return { content: [{ type: "text", text: output }] };
+}

package/framework-mcp/src/tools/framework/update_contract_hash.ts

@@ -0,0 +1,7 @@
+import { safeExec } from "../../utils/cli.js";
+import { ToolResult } from "../types.js";
+
+export function handleUpdateContractHash(projectRoot: string): ToolResult {
+    const output = safeExec("npx", ["agent-enderun", "update-contract"], projectRoot);
+    return { content: [{ type: "text", text: output }] };
+}

package/framework-mcp/src/tools/framework/update_memory.ts

@@ -0,0 +1,10 @@
+import { safeExec } from "../../utils/cli.js";
+import { ToolArgs, ToolResult } from "../types.js";
+
+export function handleUpdateProjectMemory(projectRoot: string, args: ToolArgs): ToolResult {
+    const section = args.section as string;
+    const content = args.content as string;
+    // Using execFileSync with array args prevents command injection
+    safeExec("npx", ["agent-enderun", "update_project_memory", section, content], projectRoot);
+    return { content: [{ type: "text", text: `✅ Section ${section} updated.` }] };
+}

package/framework-mcp/src/tools/index.ts

@@ -0,0 +1,31 @@
+import { TOOLS } from "./definitions.js";
+import { handleReadFile } from "./file_system/read_file.js";
+import { handleWriteFile } from "./file_system/write_file.js";
+import { handleReplaceText } from "./file_system/replace_text.js";
+import { handlePatchFile } from "./file_system/patch_file.js";
+import { handleGetFrameworkStatus } from "./framework/get_status.js";
+import { handleUpdateProjectMemory } from "./framework/update_memory.js";
+import { handleOrchestrateLoop } from "./framework/orchestrate.js";
+import { handleUpdateContractHash } from "./framework/update_contract_hash.js";
+import { handleSendAgentMessage } from "./messaging/send_message.js";
+import { handleLogAgentAction } from "./messaging/log_action.js";
+import { ToolResult, ToolArgs } from "./types.js";
+
+// Define a type for the tool handlers
+export type ToolHandler = (projectRoot: string, args: ToolArgs) => ToolResult;
+
+// Map of tool names to their handler functions
+export const toolHandlers: Record<string, ToolHandler> = {
+    read_file: handleReadFile,
+    write_file: handleWriteFile,
+    replace_text: handleReplaceText,
+    patch_file: handlePatchFile,
+    get_framework_status: handleGetFrameworkStatus,
+    update_project_memory: handleUpdateProjectMemory,
+    orchestrate_loop: handleOrchestrateLoop,
+    send_agent_message: handleSendAgentMessage,
+    log_agent_action: handleLogAgentAction,
+    update_contract_hash: handleUpdateContractHash,
+};
+
+export { TOOLS };