agent-enderun 1.10.4 → 1.11.1

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

@@ -0,0 +1,44 @@
+import fs from "fs";
+import path from "path";
+/**
+ * Ensures directory existence.
+ */
+export function ensureDir(dirPath) {
+    if (!fs.existsSync(dirPath)) {
+        fs.mkdirSync(dirPath, { recursive: true });
+    }
+}
+/**
+ * Atomically writes a text file.
+ */
+export function writeTextFileAtomic(filePath, content) {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+    const tempPath = `${filePath}.${Math.random().toString(36).slice(2, 9)}.tmp`;
+    const finalContent = content.endsWith("\n") ? content : `${content}\n`;
+    try {
+        fs.writeFileSync(tempPath, finalContent, "utf8");
+        fs.renameSync(tempPath, filePath);
+    }
+    catch (err) {
+        if (fs.existsSync(tempPath)) {
+            try {
+                fs.unlinkSync(tempPath);
+            }
+            catch { /* ignore */ }
+        }
+        throw err;
+    }
+}
+/**
+ * Atomically appends to a file (if supported by OS) or simulates it.
+ * Note: Real atomic append on POSIX is a single write() call with O_APPEND.
+ * For simplicity and robustness across platforms, we use a simple append here
+ * as the risk of corruption is lower than a full rewrite, but for logs
+ * it's acceptable.
+ */
+export function appendFileSafe(filePath, content) {
+    const dir = path.dirname(filePath);
+    ensureDir(dir);
+    fs.appendFileSync(filePath, content, "utf8");
+}

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

@@ -0,0 +1,56 @@
+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) => {
+        Metrics.saveMetric(projectRoot, {
+            timestamp: new Date().toISOString(),
+            agent,
+            action,
+            estimatedTokens: tokens
+        });
+    },
+    /**
+     * Logs an error occurrence to the observability metrics file.
+     */
+    logError: (projectRoot, agent, action, error) => {
+        Metrics.saveMetric(projectRoot, {
+            timestamp: new Date().toISOString(),
+            agent,
+            action: `ERROR: ${action}`,
+            estimatedTokens: 0,
+            error
+        });
+    },
+    /**
+     * Internal helper to save metric entries.
+     */
+    saveMetric: (projectRoot, entry) => {
+        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(entry);
+            // 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

@@ -0,0 +1,60 @@
+import path from "path";
+import fs from "fs";
+import { FRAMEWORK, MCP, UNIFIED_HUB_DIR } from "../constants.js"; // New import
+import os from "os"; // Need os.homedir()
+/**
+ * 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: ENDERUN_TEST_DIR (env) -> package.json `enderun.frameworkDir` -> `.enderun` -> other adapter dirs -> global HOME.
+ */
+export function resolveFrameworkDir(projectRoot) {
+    // For test environments, use the explicitly set test directory.
+    const testDir = process.env[MCP.TEST_DIR_ENV];
+    if (testDir)
+        return testDir;
+    // 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") {
+                // Ensure the path is relative if it's within the project, otherwise use as-is.
+                const resolvedDir = path.resolve(projectRoot, enderunConfig["frameworkDir"]);
+                if (resolvedDir.startsWith(path.resolve(projectRoot))) {
+                    return path.relative(projectRoot, resolvedDir);
+                }
+                return enderunConfig["frameworkDir"];
+            }
+        }
+    }
+    catch {
+        // ignore — fall through to filesystem scan
+    }
+    // 2. Filesystem scan in projectRoot for common framework directories
+    const localCandidates = [
+        FRAMEWORK.CORE_DIR, // .enderun
+        UNIFIED_HUB_DIR, // .agents
+        // Add other adapter specific directories if needed, or remove if unified is strictly enforced
+    ];
+    for (const candidate of localCandidates) {
+        const candidatePath = path.join(projectRoot, candidate);
+        if (fs.existsSync(candidatePath)) {
+            return candidate;
+        }
+    }
+    // 3. Fallback to global home directory.
+    const homeDir = os.homedir();
+    return path.join(homeDir, FRAMEWORK.CORE_DIR);
+}

package/framework-mcp/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@agent-enderun/mcp",
+  "version": "1.10.5",
+  "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": "^5.0.0"
+  }
+}

package/framework-mcp/src/constants.ts

@@ -0,0 +1,78 @@
+import path from "path";
+
+/**
+ * Agent Enderun — Single Source of Truth for framework constants.
+ * Import from here instead of hardcoding paths, phases, or directory names.
+ */
+
+// ─── Framework identity ───────────────────────────────────────────────────
+
+export const FRAMEWORK = {
+    NAME: "Agent Enderun",
+    CORE_DIR: ".enderun",
+    // This is the hub for unified adapter layouts (e.g. .agents/gemini, .agents/claude)
+    UNIFIED_HUB_DIR: ".agents",
+    // This is the default directory to scaffold new apps into
+    APPS_DIR: "apps",
+    // This is where all skills are stored
+    SKILLS_DIR: "skills",
+};
+
+export const FRAMEWORK_SUBDIRS = {
+    AGENTS: "agents",
+    SKILLS: "skills",
+    KNOWLEDGE: "knowledge",
+    MESSAGES: "messages",
+    MEMORY: "memory",
+    MEMORY_GRAPH: "memory-graph",
+    LOGS: "logs",
+    CONFIG: "config",
+};
+
+export const ROOT_CONFIG_FILES = {
+    MCP: "mcp.json",
+    NATIVE_MODULES: "native-modules.json",
+    TSCONFIG: "tsconfig.json",
+    ESLINT: "eslint.config.js",
+};
+
+export const MCP = {
+    // Environment variable used by MCP to identify project root
+    PROJECT_ROOT_ENV: "ENDERUN_PROJECT_ROOT",
+    // Environment variable for test mode
+    TEST_DIR_ENV: "ENDERUN_TEST_DIR",
+};
+
+export const MEMORY_FILES = {
+    STATE: "state.json",
+    SHARED_FACTS: "shared_facts.json",
+};
+
+export const NATIVE_AGENT_PATHS = {
+    gemini: ".gemini/agents",
+    claude: ".claude/agents",
+    cursor: ".cursor/rules",
+    codex: ".agents/instructions",
+    grok: ".grok",
+    "antigravity-cli": ".antigravity/agents",
+};
+
+// ─── Backward-compatible aliases ──────────────────────────────────────────
+
+export const CORE_FRAMEWORK_DIR = FRAMEWORK.CORE_DIR;
+export const UNIFIED_HUB_DIR = FRAMEWORK.UNIFIED_HUB_DIR;
+export const SKILLS_HUB_PATH = pathJoin(UNIFIED_HUB_DIR, FRAMEWORK_SUBDIRS.SKILLS);
+
+// ─── Path Helpers ─────────────────────────────────────────────────────────
+
+function pathJoin(...args: string[]): string {
+    return path.join(...args);
+}
+
+function corePath(subdir: string, filename: string): string {
+    return pathJoin(FRAMEWORK.CORE_DIR, subdir, filename);
+}
+
+export function knowledgePath(filename: string): string {
+    return corePath(FRAMEWORK_SUBDIRS.KNOWLEDGE, filename);
+}

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

@@ -0,0 +1,17 @@
+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

@@ -0,0 +1,132 @@
+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 { TOOLS, toolHandlers } from "./tools/index.js";
+
+
+// ─── Server Setup ─────────────────────────────────────────────────
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+// Robustly find package.json by walking up from __dirname
+function findPackageJson(startDir: string): string {
+    let currentDir = startDir;
+    while (currentDir !== path.parse(currentDir).root) {
+        const pkgPath = path.join(currentDir, "package.json");
+        if (fs.existsSync(pkgPath)) return pkgPath;
+        currentDir = path.dirname(currentDir);
+    }
+    throw new Error("Could not find package.json for @agent-enderun/mcp");
+}
+
+const pkgPath = findPackageJson(__dirname);
+const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+const serverVersion = pkg.version;
+
+const server = new Server(
+    {
+        name: "@agent-enderun/mcp",
+        version: serverVersion,
+    },
+    {
+        capabilities: {
+            tools: {},
+        },
+    }
+);
+
+// Basic Schema Validator for Required Fields
+function validateArgs(toolName: string, args: Record<string, unknown>): string | null {
+    const definition = TOOLS.find(t => t.name === toolName);
+    if (!definition) return `Unknown tool: ${toolName}`;
+    
+    const required = definition.inputSchema.required || [];
+    for (const field of required) {
+        if (args[field] === undefined || args[field] === null || args[field] === "") {
+            return `Missing required argument: '${field}' for tool '${toolName}'`;
+        }
+    }
+    return null;
+}
+
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return { tools: TOOLS };
+});
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const req = request as { params: { name: string, arguments?: Record<string, unknown> } };
+    const { name, arguments: args } = req.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}` }],
+            };
+        }
+
+        // 🛡️ Runtime Validation
+        const validationError = validateArgs(name, args || {});
+        if (validationError) {
+            return {
+                isError: true,
+                content: [{ type: "text" as const, text: `❌ Validation Error: ${validationError}` }],
+            };
+        }
+        
+        return await 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: `❌ Execution failed: ${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);
+});

package/framework-mcp/src/tools/control_plane/locking.ts

@@ -0,0 +1,71 @@
+import fs from "fs";
+import path from "path";
+import { ToolResult, AcquireLockArgs, ReleaseLockArgs } from "../types.js";
+import { resolveFrameworkDir } from "../../utils/security.js";
+
+/**
+ * Handles acquiring a stateful lock on a resource.
+ */
+export async function handleAcquireLock(projectRoot: string, args: AcquireLockArgs): Promise<ToolResult> {
+    const { resource, agent, ttl = 60 } = args;
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const lockDir = path.join(projectRoot, frameworkDir, "locks");
+    const lockPath = path.join(lockDir, `${resource}.lock`);
+
+    try {
+        if (!fs.existsSync(lockDir)) fs.mkdirSync(lockDir, { recursive: true });
+
+        if (fs.existsSync(lockPath)) {
+            const stat = fs.statSync(lockPath);
+            const now = new Date().getTime();
+            const age = (now - stat.mtimeMs) / 1000;
+
+            if (age < ttl) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Resource '${resource}' is currently locked by another agent.` }]
+                };
+            }
+            // Lock expired, safe to override
+            fs.unlinkSync(lockPath);
+        }
+
+        fs.writeFileSync(lockPath, JSON.stringify({ agent, timestamp: new Date().toISOString() }));
+        return {
+            content: [{ type: "text", text: `✅ Lock acquired for resource '${resource}' by ${agent}.` }]
+        };
+    } catch (e) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Failed to acquire lock: ${String(e)}` }]
+        };
+    }
+}
+
+/**
+ * Handles releasing a lock.
+ */
+export async function handleReleaseLock(projectRoot: string, args: ReleaseLockArgs): Promise<ToolResult> {
+    const { resource, agent } = args;
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const lockPath = path.join(projectRoot, frameworkDir, "locks", `${resource}.lock`);
+
+    try {
+        if (!fs.existsSync(lockPath)) {
+            return { content: [{ type: "text", text: `ℹ️ No lock found for resource '${resource}'.` }] };
+        }
+
+        const lockData = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (lockData.agent !== agent) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `❌ Denied: You do not own the lock for '${resource}'. Owned by ${lockData.agent}.` }]
+            };
+        }
+
+        fs.unlinkSync(lockPath);
+        return { content: [{ type: "text", text: `✅ Lock released for resource '${resource}' by ${agent}.` }] };
+    } catch (e) {
+        return { isError: true, content: [{ type: "text", text: `Failed to release lock: ${String(e)}` }] };
+    }
+}

package/framework-mcp/src/tools/control_plane/registry.ts

@@ -0,0 +1,38 @@
+import fs from "fs";
+import path from "path";
+import { ToolResult, RegisterAgentArgs } from "../types.js";
+import { resolveFrameworkDir } from "../../utils/security.js";
+
+/**
+ * Handles agent registration with the Control Plane.
+ * This can be used to validate permissions and active status.
+ */
+export async function handleRegisterAgent(projectRoot: string, args: RegisterAgentArgs): Promise<ToolResult> {
+    const { agent, role, capability = 5 } = args;
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const registryDir = path.join(projectRoot, frameworkDir, "registry");
+    const agentFile = path.join(registryDir, `${agent.replace("@", "")}_active.json`);
+
+    try {
+        if (!fs.existsSync(registryDir)) fs.mkdirSync(registryDir, { recursive: true });
+
+        const agentData = {
+            agent,
+            role,
+            capability,
+            last_seen: new Date().toISOString(),
+            status: "ACTIVE"
+        };
+
+        fs.writeFileSync(agentFile, JSON.stringify(agentData, null, 2));
+        
+        return {
+            content: [{ type: "text", text: `🎖️ Agent ${agent} (${role}) registered successfully in the Enderun Control Plane.` }]
+        };
+    } catch (e) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Failed to register agent: ${String(e)}` }]
+        };
+    }
+}

package/framework-mcp/src/tools/dashboard/start_dashboard.ts

@@ -0,0 +1,33 @@
+import fs from "fs";
+import path from "path";
+import { exec } from "child_process";
+import { StartDashboardArgs, ToolResult } from "../types.js";
+
+/**
+ * Starts the Enderun Web Dashboard server.
+ */
+export function handleStartDashboard(projectRoot: string, args: StartDashboardArgs): ToolResult {
+    const port = args.port || 5858;
+    const dashboardScript = path.join(projectRoot, "bin/enderun-dashboard.js");
+
+    if (!fs.existsSync(dashboardScript)) {
+        throw new Error("Dashboard server script not found in bin/enderun-dashboard.js");
+    }
+
+    try {
+        // Start the dashboard as a background process
+        exec(`node "${dashboardScript}"`, {
+            cwd: projectRoot,
+            env: { ...process.env, PORT: String(port) }
+        });
+
+        return {
+            content: [{
+                type: "text",
+                text: `🖥️ **Enderun Web Dashboard started!**\n\nAccess it at: http://localhost:${port}\n\nThis interface will show real-time agent status, system health, and orchestration logs.`
+            }]
+        };
+    } catch (e) {
+        return { isError: true, content: [{ type: "text", text: `Failed to start dashboard: ${String(e)}` }] };
+    }
+}