agent-enderun 1.1.3 → 1.1.5

package/dist/tests/shared.test.js

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { EnderunBaseError, ConfigurationError } from "../src/shared/errors.js";
+import { configManager } from "../src/shared/config.js";
+import { container } from "../src/shared/container.js";
+import { logger, LogLevel } from "../src/shared/logger.js";
+describe("Enterprise Shared Modules", () => {
+    describe("Error Hierarchy", () => {
+        it("should correctly serialize base errors to JSON", () => {
+            const err = new EnderunBaseError("Database failed", "DB_ERROR", { query: "SELECT * FROM users" });
+            const json = err.toJSON();
+            expect(json.name).toBe("EnderunBaseError");
+            expect(json.message).toBe("Database failed");
+            expect(json.code).toBe("DB_ERROR");
+            expect(json.details).toEqual({ query: "SELECT * FROM users" });
+            expect(json.stack).toBeDefined();
+        });
+        it("should subclass ConfigurationError properly", () => {
+            const err = new ConfigurationError("Missing key");
+            expect(err.code).toBe("CONFIGURATION_ERROR");
+            expect(err.message).toBe("Missing key");
+        });
+    });
+    describe("Configuration Manager", () => {
+        it("should load configuration and default nodeEnv to development or test", () => {
+            const current = configManager.get();
+            expect(current).toBeDefined();
+            expect(current.projectRoot).toBeDefined();
+            expect(["development", "production", "test"]).toContain(current.nodeEnv);
+        });
+        it("should freeze configuration values", () => {
+            const current = configManager.get();
+            expect(Object.isFrozen(current)).toBe(true);
+        });
+    });
+    describe("Service Container (DI)", () => {
+        beforeEach(() => {
+            container.reset();
+        });
+        it("should register and resolve singleton instances", () => {
+            const mockService = { api: "https://api.enderun.org" };
+            container.register("MockService", mockService);
+            const resolved = container.resolve("MockService");
+            expect(resolved).toBe(mockService);
+            expect(resolved.api).toBe("https://api.enderun.org");
+        });
+        it("should register and lazily resolve factories", () => {
+            let callCount = 0;
+            container.registerFactory("LazyService", () => {
+                callCount++;
+                return { count: callCount };
+            });
+            expect(callCount).toBe(0);
+            const resolved = container.resolve("LazyService");
+            expect(callCount).toBe(1);
+            expect(resolved.count).toBe(1);
+            // Subsequent resolutions should return cached singleton
+            const resolved2 = container.resolve("LazyService");
+            expect(callCount).toBe(1);
+            expect(resolved2.count).toBe(1);
+        });
+        it("should throw error on duplicate registration", () => {
+            container.register("Dummy", {});
+            expect(() => container.register("Dummy", {})).toThrow();
+        });
+        it("should throw error on unresolved services", () => {
+            expect(() => container.resolve("Unknown")).toThrow();
+        });
+    });
+    describe("Enterprise Logger", () => {
+        it("should configure level filters and print without crash", () => {
+            logger.configure({ minLevel: LogLevel.DEBUG, enableColors: false });
+            // Should not crash
+            logger.debug("Debug log test");
+            logger.info("Info log test", { userId: 42 });
+            logger.warn("Warn log test");
+            logger.error("Error log test");
+        });
+    });
+});
+//# sourceMappingURL=shared.test.js.map

package/dist/tests/shared.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.test.js","sourceRoot":"","sources":["../../tests/shared.test.ts"],"names":[],"mappings":"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"}

package/eslint.config.js

@@ -3,7 +3,7 @@ import js from "@eslint/js";
 import tseslint from "typescript-eslint";
 
 const styleRules = {
-    indent: ["error", 4],
+    indent: ["error", 4, { SwitchCase: 1 }],
     "linebreak-style": "off",
     quotes: ["error", "double"],
     semi: ["error", "always"],
@@ -24,6 +24,7 @@ export default tseslint.config(
             ".enderun/**",
             "panda.config.ts",
             "test-installations/**",
+            "apps/**",
         ],
     },
     js.configs.recommended,

package/framework-mcp/dist/{src/index.js → index.js}

@@ -1,11 +1,17 @@
+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));
+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: "1.1.3",
+    version: serverVersion,
 }, {
     capabilities: {
         tools: {},

package/framework-mcp/dist/{src/tools → tools}/definitions.js

@@ -85,6 +85,7 @@ export const TOOLS = [
                 content: { type: "string", description: "Task description or message content." },
                 traceId: { type: "string", description: "Active Trace ID." },
                 parentId: { type: "string", description: "Optional parent task trace ID for hierarchical tracking." },
+                priority: { type: "string", enum: ["HIGH", "NORMAL", "LOW"], description: "Optional priority level (HIGH, NORMAL, LOW). Defaults to HIGH for ALERT/ACTION." },
             },
             required: ["from", "to", "category", "content", "traceId"],
         },

package/framework-mcp/dist/{src/tools → tools}/file_system/patch_file.js

@@ -1,5 +1,6 @@
 import fs from "fs";
 import { safePath } from "../../utils/security.js";
+import { Metrics } from "../../utils/metrics.js";
 export function handlePatchFile(projectRoot, args) {
     const filePath = safePath(projectRoot, args.path);
     const lines = fs.readFileSync(filePath, "utf8").split("\n");
@@ -14,5 +15,7 @@ export function handlePatchFile(projectRoot, args) {
     }
     lines.splice(start, end - start, ...newContent);
     fs.writeFileSync(filePath, lines.join("\n"));
+    const tokens = Metrics.estimateTokens(args.newContent);
+    Metrics.logUsage(projectRoot, "@mcp", `patch_file: ${args.path}`, tokens);
     return { content: [{ type: "text", text: `✅ File patched successfully: ${args.path}` }] };
 }

package/framework-mcp/dist/{src/tools → tools}/file_system/read_file.js

@@ -1,5 +1,6 @@
 import fs from "fs";
 import { safePath } from "../../utils/security.js";
+import { Metrics } from "../../utils/metrics.js";
 export function handleReadFile(projectRoot, args) {
     const filePath = safePath(projectRoot, args.path);
     const startLine = args.startLine !== undefined ? Number(args.startLine) : undefined;
@@ -10,12 +11,16 @@ export function handleReadFile(projectRoot, args) {
         const start = startLine !== undefined ? Math.max(1, startLine) - 1 : 0;
         const end = endLine !== undefined ? Math.min(lines.length, endLine) : lines.length;
         const sliced = lines.slice(start, end).join("\n");
+        const tokens = Metrics.estimateTokens(sliced);
+        Metrics.logUsage(projectRoot, "@mcp", `read_file: ${args.path}`, tokens);
         return { content: [{ type: "text", text: sliced }] };
     }
     // Default protection limit: 1000 lines
     const DEFAULT_MAX_LINES = 1000;
     if (lines.length > DEFAULT_MAX_LINES) {
         const sliced = lines.slice(0, DEFAULT_MAX_LINES).join("\n");
+        const tokens = Metrics.estimateTokens(sliced);
+        Metrics.logUsage(projectRoot, "@mcp", `read_file: ${args.path} (truncated)`, tokens);
         return {
             content: [{
                     type: "text",
@@ -23,5 +28,7 @@ export function handleReadFile(projectRoot, args) {
                 }]
         };
     }
+    const tokens = Metrics.estimateTokens(content);
+    Metrics.logUsage(projectRoot, "@mcp", `read_file: ${args.path}`, tokens);
     return { content: [{ type: "text", text: content }] };
 }

package/framework-mcp/dist/{src/tools → tools}/file_system/replace_text.js

@@ -1,5 +1,6 @@
 import fs from "fs";
 import { safePath } from "../../utils/security.js";
+import { Metrics } from "../../utils/metrics.js";
 export function handleReplaceText(projectRoot, args) {
     const filePath = safePath(projectRoot, args.path);
     let content = fs.readFileSync(filePath, "utf8");
@@ -27,5 +28,7 @@ export function handleReplaceText(projectRoot, args) {
         content = content.replace(oldText, newText);
     }
     fs.writeFileSync(filePath, content);
+    const tokens = Metrics.estimateTokens(newText);
+    Metrics.logUsage(projectRoot, "@mcp", `replace_text: ${args.path}`, tokens);
     return { content: [{ type: "text", text: `✅ Surgical edit successful in ${args.path}` }] };
 }

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

@@ -0,0 +1,74 @@
+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, ".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/types.js

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

package/framework-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-enderun/mcp",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Agent Enderun Model Context Protocol (MCP) Server",
   "type": "module",
   "scripts": {

package/framework-mcp/src/index.ts

@@ -1,3 +1,6 @@
+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 {
@@ -11,10 +14,14 @@ 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: "1.1.3",
+        version: serverVersion,
     },
     {
         capabilities: {

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

@@ -87,6 +87,7 @@ export const TOOLS: ToolDefinition[] = [
                 content: { type: "string", description: "Task description or message content." },
                 traceId: { type: "string", description: "Active Trace ID." },
                 parentId: { type: "string", description: "Optional parent task trace ID for hierarchical tracking." },
+                priority: { type: "string", enum: ["HIGH", "NORMAL", "LOW"], description: "Optional priority level (HIGH, NORMAL, LOW). Defaults to HIGH for ALERT/ACTION." },
             },
             required: ["from", "to", "category", "content", "traceId"],
         },

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

@@ -1,6 +1,7 @@
 import fs from "fs";
 import { safePath } from "../../utils/security.js";
 import { ToolArgs, ToolResult } from "../types.js";
+import { Metrics } from "../../utils/metrics.js";
 
 export function handlePatchFile(projectRoot: string, args: ToolArgs): ToolResult {
     const filePath = safePath(projectRoot, args.path as string);
@@ -18,6 +19,11 @@ export function handlePatchFile(projectRoot: string, args: ToolArgs): ToolResult
 
     lines.splice(start, end - start, ...newContent);
     fs.writeFileSync(filePath, lines.join("\n"));
+
+    const tokens = Metrics.estimateTokens(args.newContent as string);
+    Metrics.logUsage(projectRoot, "@mcp", `patch_file: ${args.path}`, tokens);
+
     return { content: [{ type: "text", text: `✅ File patched successfully: ${args.path}` }] };
 }
 
+

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

@@ -1,6 +1,7 @@
 import fs from "fs";
 import { safePath } from "../../utils/security.js";
 import { ToolArgs, ToolResult } from "../types.js";
+import { Metrics } from "../../utils/metrics.js";
 
 export function handleReadFile(projectRoot: string, args: ToolArgs): ToolResult {
     const filePath = safePath(projectRoot, args.path as string);
@@ -9,11 +10,12 @@ export function handleReadFile(projectRoot: string, args: ToolArgs): ToolResult
 
     const content = fs.readFileSync(filePath, "utf8");
     const lines = content.split(/\r?\n/);
-
     if (startLine !== undefined || endLine !== undefined) {
         const start = startLine !== undefined ? Math.max(1, startLine) - 1 : 0;
         const end = endLine !== undefined ? Math.min(lines.length, endLine) : lines.length;
         const sliced = lines.slice(start, end).join("\n");
+        const tokens = Metrics.estimateTokens(sliced);
+        Metrics.logUsage(projectRoot, "@mcp", `read_file: ${args.path}`, tokens);
         return { content: [{ type: "text", text: sliced }] };
     }
 
@@ -21,6 +23,8 @@ export function handleReadFile(projectRoot: string, args: ToolArgs): ToolResult
     const DEFAULT_MAX_LINES = 1000;
     if (lines.length > DEFAULT_MAX_LINES) {
         const sliced = lines.slice(0, DEFAULT_MAX_LINES).join("\n");
+        const tokens = Metrics.estimateTokens(sliced);
+        Metrics.logUsage(projectRoot, "@mcp", `read_file: ${args.path} (truncated)`, tokens);
         return {
             content: [{
                 type: "text",
@@ -29,5 +33,7 @@ export function handleReadFile(projectRoot: string, args: ToolArgs): ToolResult
         };
     }
 
+    const tokens = Metrics.estimateTokens(content);
+    Metrics.logUsage(projectRoot, "@mcp", `read_file: ${args.path}`, tokens);
     return { content: [{ type: "text", text: content }] };
 }

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

@@ -1,6 +1,7 @@
 import fs from "fs";
 import { safePath } from "../../utils/security.js";
 import { ToolArgs, ToolResult } from "../types.js";
+import { Metrics } from "../../utils/metrics.js";
 
 export function handleReplaceText(projectRoot: string, args: ToolArgs): ToolResult {
     const filePath = safePath(projectRoot, args.path as string);
@@ -34,5 +35,10 @@ export function handleReplaceText(projectRoot: string, args: ToolArgs): ToolResu
     }
     
     fs.writeFileSync(filePath, content);
+
+    const tokens = Metrics.estimateTokens(newText);
+    Metrics.logUsage(projectRoot, "@mcp", `replace_text: ${args.path}`, tokens);
+
     return { content: [{ type: "text", text: `✅ Surgical edit successful in ${args.path}` }] };
 }
+

package/framework-mcp/src/tools/messaging/send_message.ts

@@ -15,22 +15,42 @@ export async function handleSendAgentMessage(projectRoot: string, args: ToolArgs
 
     // Hermes Lock Protocol: Retry 3 times with 500ms delay
     let retries = 3;
-    while (retries > 0 && fs.existsSync(lockPath)) {
-        const stats = fs.statSync(lockPath);
-        if (Date.now() - stats.mtimeMs > 5000) {
-            fs.unlinkSync(lockPath);
+    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;
-        }
-        retries--;
-        if (retries > 0) {
-            await new Promise((resolve) => setTimeout(resolve, 500));
+        } catch (err: unknown) {
+            const error = err as { code?: string; message?: string };
+            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 };
+            }
         }
     }
 
-    try {
-        fs.mkdirSync(messagesDir, { recursive: true });
-        fs.writeFileSync(lockPath, `Locked by ${from} at ${new Date().toISOString()}`);
+    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,
@@ -38,12 +58,19 @@ export async function handleSendAgentMessage(projectRoot: string, args: ToolArgs
             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 (fs.existsSync(lockPath)) fs.unlinkSync(lockPath);
+        if (acquired && fs.existsSync(lockPath)) {
+            try {
+                fs.unlinkSync(lockPath);
+            } catch {
+                // ignore
+            }
+        }
     }
 }

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

@@ -35,6 +35,7 @@ export interface ToolArgs {
     allowMultiple?: boolean;
     timeout?: number;
     from?: string;
+    priority?: "HIGH" | "NORMAL" | "LOW";
 }
 
 export interface ToolResult {

package/framework-mcp/tests/tools/file_system/file_system_tools.test.ts

@@ -68,6 +68,20 @@ describe("File System Tools", () => {
             expect(result.content[0].text).toContain("✅ Surgical edit successful");
             expect(fs.readFileSync(TEST_FILE, "utf8")).toBe("hello there there");
         });
+
+        it("should log usage to metrics.json upon replace", () => {
+            fs.writeFileSync(TEST_FILE, "hello world", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                oldText: "world",
+                newText: "there",
+            };
+            handleReplaceText(TEST_DIR, args);
+            const metricsPath = path.join(TEST_DIR, ".gemini/observability/metrics.json");
+            expect(fs.existsSync(metricsPath)).toBe(true);
+            const metrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            expect(metrics[0].action).toContain("replace_text");
+        });
     });
 
     describe("handlePatchFile", () => {
@@ -105,6 +119,21 @@ describe("File System Tools", () => {
             };
             expect(() => handlePatchFile(TEST_DIR, args)).toThrowError("Invalid end line");
         });
+
+        it("should log usage to metrics.json upon patch", () => {
+            fs.writeFileSync(TEST_FILE, "line1\nline2\nline3\nline4", "utf8");
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                startLine: 2,
+                endLine: 3,
+                newContent: "patched2\npatched3",
+            };
+            handlePatchFile(TEST_DIR, args);
+            const metricsPath = path.join(TEST_DIR, ".gemini/observability/metrics.json");
+            expect(fs.existsSync(metricsPath)).toBe(true);
+            const metrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            expect(metrics[0].action).toContain("patch_file");
+        });
     });
 
     describe("handleReadFile", () => {
@@ -148,6 +177,19 @@ describe("File System Tools", () => {
             expect(fs.readFileSync(TEST_FILE, "utf8")).toBe("hello world");
         });
 
+        it("should write new file and log usage to metrics.json", () => {
+            const args: ToolArgs = {
+                path: TEST_FILE,
+                content: "hello world"
+            };
+            handleWriteFile(TEST_DIR, args);
+            const metricsPath = path.join(TEST_DIR, ".gemini/observability/metrics.json");
+            expect(fs.existsSync(metricsPath)).toBe(true);
+            const metrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            expect(metrics[0].action).toContain("write_file");
+            expect(metrics[0].estimatedTokens).toBeGreaterThan(0);
+        });
+
         it("should append update to PROJECT_MEMORY.md if it exists", () => {
             fs.mkdirSync(MEMORY_DIR, { recursive: true });
             fs.writeFileSync(MEMORY_FILE, "## CURRENT STATUS\n", "utf8");