agent-enderun 1.1.4 → 1.1.5

package/framework-mcp/tests/tools/messaging/send_message.test.ts

@@ -0,0 +1,136 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import fs from "fs";
+import path from "path";
+import { handleSendAgentMessage } from "../../../src/tools/messaging/send_message.js";
+import { ToolArgs } from "../../../src/tools/types.js";
+
+const TEST_DIR = path.resolve(__dirname, "../../_temp_messaging_tests");
+const MESSAGES_DIR = path.join(TEST_DIR, ".gemini/messages");
+const LOCK_FILE = path.join(MESSAGES_DIR, ".lock");
+
+beforeEach(() => {
+    fs.mkdirSync(TEST_DIR, { recursive: true });
+    // Write a dummy package.json to test directory to lock frameworkDir as .gemini
+    const dummyPkg = {
+        name: "test-pkg",
+        enderun: {
+            frameworkDir: ".gemini"
+        }
+    };
+    fs.writeFileSync(path.join(TEST_DIR, "package.json"), JSON.stringify(dummyPkg, null, 2), "utf8");
+});
+
+afterEach(() => {
+    fs.rmSync(TEST_DIR, { recursive: true, force: true });
+});
+
+describe("Hermes Lock Protocol & Message sending", () => {
+    it("should successfully send message when lock is not present", async () => {
+        const args: ToolArgs = {
+            to: "@backend",
+            from: "@manager",
+            category: "ACTION",
+            content: "Build database models",
+            traceId: "T-123",
+            priority: "HIGH"
+        };
+
+        const result = await handleSendAgentMessage(TEST_DIR, args);
+        expect(result.content[0].text).toContain("✅ Message sent to @backend");
+
+        // Verify the message file contains the sent message
+        const messageFilePath = path.join(MESSAGES_DIR, "backend.json");
+        expect(fs.existsSync(messageFilePath)).toBe(true);
+
+        const content = fs.readFileSync(messageFilePath, "utf8");
+        const msg = JSON.parse(content.trim());
+        expect(msg.from).toBe("@manager");
+        expect(msg.to).toBe("@backend");
+        expect(msg.category).toBe("ACTION");
+        expect(msg.content).toBe("Build database models");
+        expect(msg.traceId).toBe("T-123");
+        expect(msg.priority).toBe("HIGH");
+        expect(msg.status).toBe("PENDING");
+    });
+
+    it("should retry and fail to send message if lock is kept busy", async () => {
+        // Prepare a busy lock file
+        fs.mkdirSync(MESSAGES_DIR, { recursive: true });
+        fs.writeFileSync(LOCK_FILE, "Locked by @test at " + new Date().toISOString(), "utf8");
+
+        const args: ToolArgs = {
+            to: "@backend",
+            from: "@manager",
+            category: "ACTION",
+            content: "Build database models",
+            traceId: "T-123"
+        };
+
+        const startTime = Date.now();
+        const result = await handleSendAgentMessage(TEST_DIR, args);
+        const duration = Date.now() - startTime;
+
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain("❌ Could not send message to @backend: Hermes lock is busy.");
+        // Retries takes 3 attempts with 500ms delay -> duration should be at least ~1000ms
+        expect(duration).toBeGreaterThanOrEqual(1000);
+    });
+
+    it("should bypass and acquire lock if existing lock is stale (older than 5s)", async () => {
+        fs.mkdirSync(MESSAGES_DIR, { recursive: true });
+        // Set lock file mtime to 10 seconds ago
+        fs.writeFileSync(LOCK_FILE, "Locked by @test at " + new Date().toISOString(), "utf8");
+        const tenSecondsAgo = new Date(Date.now() - 10000);
+        fs.utimesSync(LOCK_FILE, tenSecondsAgo, tenSecondsAgo);
+
+        const args: ToolArgs = {
+            to: "@backend",
+            from: "@manager",
+            category: "ACTION",
+            content: "Build database models",
+            traceId: "T-123"
+        };
+
+        const result = await handleSendAgentMessage(TEST_DIR, args);
+        expect(result.content[0].text).toContain("✅ Message sent to @backend");
+        expect(fs.existsSync(LOCK_FILE)).toBe(false); // Lock should have been unlinked in finally
+    });
+
+    it("should safely resolve concurrent messages and execute them in sequence", async () => {
+        const send1Promise = handleSendAgentMessage(TEST_DIR, {
+            to: "@backend",
+            from: "@manager",
+            category: "ACTION",
+            content: "Job 1",
+            traceId: "T-123"
+        });
+
+        // Delay starting the second call slightly to make sure lock is acquired by Job 1 first
+        await new Promise((resolve) => setTimeout(resolve, 50));
+
+        const send2Promise = handleSendAgentMessage(TEST_DIR, {
+            to: "@backend",
+            from: "@frontend",
+            category: "INFO",
+            content: "Job 2",
+            traceId: "T-123"
+        });
+
+        const [res1, res2] = await Promise.all([send1Promise, send2Promise]);
+
+        expect(res1.isError).toBeFalsy();
+        expect(res2.isError).toBeFalsy();
+        expect(res1.content[0].text).toContain("✅ Message sent to @backend");
+        expect(res2.content[0].text).toContain("✅ Message sent to @backend");
+
+        // Verify both messages exist in order in the message log file
+        const messageFilePath = path.join(MESSAGES_DIR, "backend.json");
+        const lines = fs.readFileSync(messageFilePath, "utf8").trim().split("\n");
+        expect(lines.length).toBe(2);
+
+        const msg1 = JSON.parse(lines[0]);
+        const msg2 = JSON.parse(lines[1]);
+        expect(msg1.content).toBe("Job 1");
+        expect(msg2.content).toBe("Job 2");
+    });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-enderun",
-  "version": "1.1.4",
+  "version": "1.1.5",
   "description": "The Supreme AI Governance & Orchestration Framework for Enterprise Development",
   "author": "Yusuf BEKAR",
   "license": "MIT",
@@ -46,6 +46,7 @@
     "GROK.md",
     "agent.md",
     "docs",
+    "templates",
     ".cursor",
     ".github"
   ],
@@ -80,14 +81,16 @@
     "tsx": "^4.22.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.60.0",
-    "vitest": "^4.1.7",
-    "zod": "^3.24.2"
+    "vitest": "^4.1.7"
   },
   "enderun": {
-    "version": "1.1.4",
-    "initializedAt": "2026-06-04T18:51:28.970Z"
+    "version": "1.1.5",
+    "initializedAt": "2026-06-04T18:51:28.970Z",
+    "frameworkDir": ".gemini"
   },
+
   "dependencies": {
-    "chalk": "^5.6.2"
+    "chalk": "^5.6.2",
+    "zod": "^3.24.2"
   }
 }

package/src/cli/adapters.ts

@@ -2,6 +2,7 @@ import path from "path";
 import fs from "fs";
 import { writeJsonFile } from "./utils/fs.js";
 import { getPackageRoot } from "./utils/pkg.js";
+import { ALL_AGENTS } from "../modules/agents/definitions.js";
 
 import type { AdapterId, AdapterConfig } from "./adapters/types.js";
 export { ADAPTER_IDS, type AdapterId, type AdapterRole, type AdapterConfig } from "./adapters/types.js";
@@ -48,10 +49,16 @@ export const FRAMEWORK_DIR_CANDIDATES = [
 const SHIM_FILES = (Object.keys(ADAPTERS) as AdapterId[]).map((id) => ADAPTERS[id].shimFile);
 
 export function resolveAdapter(input?: string): AdapterConfig {
-    const normalized = (input || "gemini").toLowerCase() as AdapterId;
+    let normalized = (input || "gemini").toLowerCase();
+    if (normalized === "antigravity") {
+        normalized = "antigravity-cli";
+    } else if (normalized === "copilot" || normalized === "github") {
+        normalized = "codex";
+    }
+
     let config: AdapterConfig;
     if (normalized in ADAPTERS) {
-        config = { ...ADAPTERS[normalized] };
+        config = { ...ADAPTERS[normalized as AdapterId] };
     } else {
         console.warn(`⚠️  Unknown adapter "${input}". Falling back to gemini.`);
         config = { ...ADAPTERS.gemini };
@@ -163,9 +170,6 @@ export function buildMcpServerEntry(projectRoot: string) {
 }
 
 export function generateAdapterAgentRules(projectRoot: string, frameworkDir: string, adapterId: AdapterId): void {
-    const agentsDir = path.join(projectRoot, frameworkDir, "agents");
-    if (!fs.existsSync(agentsDir)) return;
-
     const adapter = ADAPTERS[adapterId];
     if (!adapter || !adapter.rulesDir || !adapter.rulesExt) return;
 
@@ -174,7 +178,6 @@ export function generateAdapterAgentRules(projectRoot: string, frameworkDir: str
 
     try {
         fs.mkdirSync(destRulesDir, { recursive: true });
-        const files = fs.readdirSync(agentsDir).filter((f) => f.endsWith(".json") && f !== "agent_army_schema.json");
 
         const GLOB_MAP: Record<string, string> = {
             backend: "apps/backend/**/*",
@@ -191,13 +194,11 @@ export function generateAdapterAgentRules(projectRoot: string, frameworkDir: str
             manager: "*",
         };
 
-        for (const file of files) {
-            const filePath = path.join(agentsDir, file);
-            const agent = JSON.parse(fs.readFileSync(filePath, "utf8"));
+        for (const agent of ALL_AGENTS) {
             const name = agent.name;
             const displayName = agent.displayName || name;
             const description = agent.description || "";
-            const systemPrompt = agent.customAgentSpec?.customAgent?.systemPromptSections?.[0]?.content || "";
+            const systemPrompt = agent.instructions || "";
             const glob = GLOB_MAP[name] || "*";
             const ruleDestPath = path.join(destRulesDir, `${name}${fileExt}`);
 
@@ -248,12 +249,13 @@ ${systemPrompt}
 
             fs.writeFileSync(ruleDestPath, mdcContent);
         }
-        console.warn(`✅ Generated 12 Agent Rules under ${path.relative(projectRoot, destRulesDir)}/`);
+        console.warn(`✅ Generated 13 Agent Rules under ${path.relative(projectRoot, destRulesDir)}/`);
     } catch (e) {
         console.warn(`⚠️  Failed to generate Agent rules: ${e}`);
     }
 }
 
+
 export function runAdapterPostInit(adapter: AdapterConfig, projectRoot: string): void {
     const mcpEntry = buildMcpServerEntry(projectRoot);
     const mcpBlock = { mcpServers: { "agent-enderun": mcpEntry } };

package/src/cli/commands/approve.ts

@@ -0,0 +1,65 @@
+import fs from "fs";
+import path from "path";
+import { getFrameworkDir } from "../utils/memory.js";
+import { UI } from "../utils/ui.js";
+
+import { HermesMessageSchema } from "./orchestrate.js";
+
+export function approveCommand(traceId: string) {
+    const frameworkDir = getFrameworkDir();
+    const messagesDir = path.join(frameworkDir, "messages");
+
+    if (!fs.existsSync(messagesDir)) {
+        UI.error("No messages directory found.");
+        process.exit(1);
+    }
+
+    const files = fs.readdirSync(messagesDir).filter((f) => f.endsWith(".json"));
+    let found = false;
+
+    for (const file of files) {
+        const filePath = path.join(messagesDir, file);
+        try {
+            const content = fs.readFileSync(filePath, "utf8").trim();
+            if (!content) continue;
+            const lines = content.split("\n");
+            let updated = false;
+            const newLines = lines.map((line) => {
+                if (!line.trim()) return line;
+                try {
+                    const parsed = JSON.parse(line);
+                    const msg = HermesMessageSchema.parse(parsed);
+                    if (msg.traceId === traceId && msg.status === "PENDING" && (msg.category === "ALERT" || msg.category === "ACTION")) {
+                        msg.status = "APPROVED";
+                        updated = true;
+                        found = true;
+                        UI.success(`Approved message from ${msg.from} to ${msg.to} (Action: ${msg.action || "None"})`);
+                    }
+                    return JSON.stringify(msg);
+                } catch (e) {
+                    UI.error(`Skipping invalid Hermes message during approval: ${(e as Error).message}`);
+                    return line;
+                }
+            });
+
+            if (updated) {
+                fs.writeFileSync(filePath, newLines.join("\n") + "\n", "utf8");
+            }
+        } catch (e) {
+            UI.error(`Error reading or updating message file ${file}: ${(e as Error).message}`);
+        }
+    }
+
+    if (found) {
+        // Log user approval to audit log
+        const auditPath = path.join(frameworkDir, "observability/audit_log.md");
+        if (fs.existsSync(auditPath)) {
+            const logEntry = "\n- **[" + new Date().toISOString() + "]** USER -> @manager | APPROVED | Trace: " + traceId;
+            fs.appendFileSync(auditPath, logEntry);
+        }
+        UI.success("Successfully approved Trace: " + traceId);
+    } else {
+        UI.error("No pending approval request found for Trace ID: " + traceId);
+        process.exit(1);
+    }
+}

package/src/cli/commands/check.ts

@@ -2,7 +2,7 @@ import fs from "fs";
 import path from "path";
 import { execSync } from "child_process";
 
-import { getFrameworkDir, getMemoryPath } from "../utils/memory.js";
+import { getFrameworkDir, getMemoryPath, getConfiguredPaths } from "../utils/memory.js";
 import { getPackageVersion, getValidatorPath } from "../utils/pkg.js";
 import { UI } from "../utils/ui.js";
 
@@ -14,6 +14,7 @@ export function checkCommand() {
 
     const frameworkDir = getFrameworkDir();
     const memoryPath = getMemoryPath();
+    const pathsMap = getConfiguredPaths();
 
     UI.success(`Using framework dir: ${frameworkDir}`);
 
@@ -21,6 +22,27 @@ export function checkCommand() {
     if (frameworkDir === ".github") knowledgeDir = "instructions";
 
     const constitutionPath = fs.existsSync(path.join(process.cwd(), "ENDERUN.md")) ? "ENDERUN.md" : path.join(frameworkDir, "ENDERUN.md");
+    
+    const rootPandaPath = path.join(process.cwd(), "panda.config.ts");
+    const appPandaPath = path.join(pathsMap.frontend, "panda.config.ts");
+
+    if (fs.existsSync(rootPandaPath)) {
+        UI.error(`Panda CSS config must NOT be at the root directory! Move it to '${pathsMap.frontend}/panda.config.ts'.`);
+        issues++;
+    }
+
+    let isFrameworkDevelopment = false;
+    try {
+        const localPkgPath = path.join(process.cwd(), "package.json");
+        if (fs.existsSync(localPkgPath)) {
+            const localPkg = JSON.parse(fs.readFileSync(localPkgPath, "utf8"));
+            if (localPkg.name === "agent-enderun") {
+                isFrameworkDevelopment = true;
+            }
+        }
+    } catch {
+        // ignore
+    }
 
     const checks = [
         { name: "Constitution (ENDERUN.md)", path: constitutionPath },
@@ -29,10 +51,10 @@ export function checkCommand() {
         { name: "Framework Config (config.json)", path: path.join(frameworkDir, "config.json") },
         { name: "Agent Status (STATUS.md)", path: path.join(frameworkDir, "STATUS.md") },
         { name: "MCP Config (mcp.json)", path: "mcp.json" },
-        { name: "ESLint Config (eslint.config.js)", path: "eslint.config.js" },
+        { name: "ESLint Config (eslint.config.js)", path: "eslint.config.js", optional: !isFrameworkDevelopment },
         { name: "ESLint Standards", path: path.join(frameworkDir, `${knowledgeDir}/eslint-standards.md`) },
-        { name: "MCP Server", path: "framework-mcp/package.json" },
-        { name: "Panda CSS Config", path: "panda.config.ts", optional: true },
+        ...(isFrameworkDevelopment ? [{ name: "MCP Server", path: "framework-mcp/package.json" }] : []),
+        { name: "Panda CSS Config", path: appPandaPath, optional: true },
         { name: "Brain Dashboard", path: path.join(frameworkDir, "BRAIN_DASHBOARD.md") },
     ];
 
@@ -73,6 +95,11 @@ export function checkCommand() {
         UI.success("No forbidden 'console.log' detected.");
     }
 
+    const rootTestFiles = checkRootTestFiles();
+    if (rootTestFiles.length > 0) {
+        UI.warning(`Test files found in the root directory: ${rootTestFiles.join(", ")}. It is recommended to place all test files under the 'tests/' folder or application-specific directories.`);
+    }
+
     try {
         execSync("npx tsc --noEmit", { stdio: "pipe" });
         UI.success("TypeScript type check PASSED.");
@@ -81,6 +108,51 @@ export function checkCommand() {
         issues++;
     }
 
+    interface MetricEntry {
+        timestamp: string;
+        agent: string;
+        action: string;
+        estimatedTokens: number;
+    }
+
+    const metricsPath = path.join(frameworkDir, "observability/metrics.json");
+    if (fs.existsSync(metricsPath)) {
+        try {
+            const raw = fs.readFileSync(metricsPath, "utf8");
+            const metrics: MetricEntry[] = JSON.parse(raw);
+            if (Array.isArray(metrics) && metrics.length > 0) {
+                console.warn("\n📊  Token Consumption Report:");
+                let totalTokens = 0;
+                const breakdown: Record<string, { count: number; tokens: number }> = {};
+
+                for (const entry of metrics) {
+                    const tokens = typeof entry.estimatedTokens === "number" ? entry.estimatedTokens : 0;
+                    totalTokens += tokens;
+
+                    const actionName = (entry.action || "unknown").split(":")[0].trim();
+                    if (!breakdown[actionName]) {
+                        breakdown[actionName] = { count: 0, tokens: 0 };
+                    }
+                    breakdown[actionName].count += 1;
+                    breakdown[actionName].tokens += tokens;
+                }
+
+                console.warn(`  - Total Operations: ${metrics.length}`);
+                console.warn(`  - Total Estimated Tokens: ${totalTokens}`);
+                console.warn("\n  Breakdown by Action:");
+                for (const [action, data] of Object.entries(breakdown)) {
+                    console.warn(`    - ${action}: ${data.count} ops (${data.tokens} tokens)`);
+                }
+            } else {
+                console.warn("\n📊  Token Consumption Report: No token usage logged yet.");
+            }
+        } catch {
+            console.warn("\n📊  Token Consumption Report: Could not read or parse metrics file.");
+        }
+    } else {
+        console.warn("\n📊  Token Consumption Report: No token usage logged yet.");
+    }
+
     if (issues === 0) {
         UI.success("\n🚀 All systems green! Enderun Core is ready.");
     } else {
@@ -101,12 +173,33 @@ function checkConsoleLogs(): string[] {
             else if (file.endsWith(".ts") && !file.includes(".test.")) {
                 const content = fs.readFileSync(fullPath, "utf8");
                 const target = "console." + "log(";
-                if (content.includes(target) && !fullPath.includes("check.ts")) {
+                if (content.includes(target) && !fullPath.includes("check.ts") && !fullPath.includes("logger.ts")) {
                     issues.push(fullPath);
                 }
+
             }
         }
     };
     walk(srcDir);
     return issues;
 }
+
+function checkRootTestFiles(): string[] {
+    const rootDir = process.cwd();
+    if (!fs.existsSync(rootDir)) return [];
+    const files = fs.readdirSync(rootDir);
+    const testFiles: string[] = [];
+    for (const file of files) {
+        const fullPath = path.join(rootDir, file);
+        try {
+            if (fs.statSync(fullPath).isFile()) {
+                if (file.includes(".test.") || file.includes(".spec.")) {
+                    testFiles.push(file);
+                }
+            }
+        } catch {
+            // Ignore stat errors for broken symlinks or permission issues
+        }
+    }
+    return testFiles;
+}

package/src/cli/commands/contract.ts

@@ -1,7 +1,7 @@
 import path from "path";
 import fs from "fs";
-import crypto from "crypto";
 import { getConfiguredPaths } from "../utils/memory.js";
+import { computeTypesHash } from "../utils/fs.js";
 
 /**
  * Verify type safety between backend and frontend contracts.
@@ -17,20 +17,7 @@ export function verifyApiContractCommand() {
         process.exit(1);
     }
 
-    const walk = (d: string): string[] => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => {
-        const fullPath = path.join(d, e.name);
-        return e.isDirectory() ? walk(fullPath) : (e.name.endsWith(".ts") ? [fullPath] : []);
-    });
-
-    const hash = crypto.createHash("sha256");
-    for (const filePath of walk(sharedDir).sort()) {
-        hash.update(path.relative(projectRoot, filePath));
-        hash.update("\0");
-        hash.update(fs.readFileSync(filePath));
-        hash.update("\0");
-    }
-
-    const currentHash = hash.digest("hex");
+    const currentHash = computeTypesHash(projectRoot, sharedDir);
     const contract = JSON.parse(fs.readFileSync(contractPath, "utf8"));
 
     if (contract.contract_hash === currentHash) {
@@ -58,20 +45,7 @@ export function updateApiContractCommand() {
         process.exit(1);
     }
 
-    const walk = (d: string): string[] => fs.readdirSync(d, { withFileTypes: true }).flatMap((e) => {
-        const fullPath = path.join(d, e.name);
-        return e.isDirectory() ? walk(fullPath) : (e.name.endsWith(".ts") ? [fullPath] : []);
-    });
-
-    const hash = crypto.createHash("sha256");
-    for (const filePath of walk(sharedDir).sort()) {
-        hash.update(path.relative(projectRoot, filePath));
-        hash.update("\0");
-        hash.update(fs.readFileSync(filePath));
-        hash.update("\0");
-    }
-
-    const currentHash = hash.digest("hex");
+    const currentHash = computeTypesHash(projectRoot, sharedDir);
     
     const contractData = {
         contract_hash: currentHash,