agent-enderun 1.1.9 → 1.10.0

package/src/cli/commands/orchestrate.ts

@@ -1,17 +1,20 @@
 import fs from "fs";
 import path from "path";
 import chalk from "chalk";
-import { getFrameworkDir } from "../utils/memory.js";
+import { getFrameworkDir, updateDocumentStore, readStatus } from "../utils/memory.js";
 import { UI } from "../utils/ui.js";
+import { writeTextFile, appendFile } from "../utils/fs.js";
 import { z } from "zod";
 import { logger } from "../../shared/logger.js";
+import { TaskRequestSchema } from "../../contracts/tasks.js";
+import { sleep } from "../utils/time.js";
 
 export const HermesMessageSchema = z.object({
     timestamp: z.string(),
     from: z.string(),
     to: z.string(),
     category: z.enum(["ACTION", "DELEGATION", "SUBTASK", "REPLY", "ALERT"]),
-    content: z.string(),
+    content: z.string(), // This is the payload to be validated
     traceId: z.string(),
     parentId: z.string().optional(),
     status: z.enum(["PENDING", "PROCESSED", "WAITING", "APPROVED"]),
@@ -21,173 +24,191 @@ export const HermesMessageSchema = z.object({
 
 export type HermesMessage = z.infer<typeof HermesMessageSchema>;
 
+// Global status cache for in-memory optimization
+let agentStatusCache: Record<string, { state: string; task: string; lastUpdated?: string }> = {};
+let isLooping = false;
+
 export async function orchestrateCommand() {
+    UI.intent("Hermes Message Broker", "Starting the live agent orchestration loop...");
+
     const frameworkDir = getFrameworkDir();
     const messagesDir = path.join(frameworkDir, "messages");
 
-    // Check for agent timeouts (e.g. 30 minutes in EXECUTING state)
-    const statusPath = path.join(frameworkDir, "STATUS.md");
-    if (fs.existsSync(statusPath)) {
-        try {
-            const content = fs.readFileSync(statusPath, "utf8");
-            const lines = content.split("\n");
-            let updatedStatus = false;
-            const newLines = lines.map(line => {
-                if (line.includes("| @") && line.includes("| EXECUTING |")) {
-                    const parts = line.split("|");
-                    if (parts.length >= 7) {
-                        const lastUpdatedStr = parts[4].trim();
-                        if (lastUpdatedStr && lastUpdatedStr !== "-") {
-                            const lastUpdatedTime = Date.parse(lastUpdatedStr);
-                            if (!isNaN(lastUpdatedTime) && Date.now() - lastUpdatedTime > 30 * 60 * 1000) {
-                                const agentName = parts[1].trim();
-                                UI.error(`⚠️  Agent ${agentName} has TIMED OUT (in EXECUTING state for >30m). Transitioning to BLOCKED.`);
-                                parts[2] = " BLOCKED ";
-                                parts[3] = " Timeout occurred ";
-                                parts[4] = ` ${new Date().toISOString()} `;
-                                updatedStatus = true;
-                                
-                                // Log to audit log
-                                const auditPath = path.join(frameworkDir, "observability/audit_log.md");
-                                if (fs.existsSync(auditPath)) {
-                                    const logEntry = `\n- **[${new Date().toISOString()}]** ${agentName} status auto-escalated to BLOCKED due to 30m execution timeout.`;
-                                    fs.appendFileSync(auditPath, logEntry);
-                                }
-                                return parts.join("|");
-                            }
-                        }
-                    }
+    // Graceful Shutdown Handling
+    const shutdown = async () => {
+        if (!isLooping) return;
+        isLooping = false;
+        UI.warning("\n🛑 Shutdown signal received. Cleaning up Hermes loop...");
+        // Additional cleanup like releasing global locks could go here
+        process.exit(0);
+    };
+
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+
+    isLooping = true;
+
+    while (isLooping) {
+        // Initial load from disk to sync the cache
+        if (Object.keys(agentStatusCache).length === 0) {
+            const diskStatus = readStatus();
+            agentStatusCache = diskStatus || {};
+        }
+
+        // Check for agent timeouts (e.g. 30 minutes in EXECUTING state)
+        const agentStatuses = readStatus();
+        let updatedStatus = false;
+        for (const [agentName, info] of Object.entries(agentStatuses)) {
+            const { state, lastUpdated } = info as { state: string; task: string; lastUpdated?: string };
+            if (state === "EXECUTING" && lastUpdated) {
+                const lastUpdatedTime = Date.parse(lastUpdated);
+                if (!isNaN(lastUpdatedTime) && Date.now() - lastUpdatedTime > 30 * 60 * 1000) {
+                    UI.error(`⚠️  Agent ${agentName} has TIMED OUT (in EXECUTING state for >30m). Transitioning to BLOCKED.`);
+                    agentStatuses[agentName] = { state: "BLOCKED", task: "Timeout occurred", lastUpdated: new Date().toISOString() };
+                    updatedStatus = true;
                 }
-                return line;
-            });
-            if (updatedStatus) {
-                fs.writeFileSync(statusPath, newLines.join("\n"));
             }
-        } catch (err) {
-            UI.error("Ajan zaman aşımı kontrolü sırasında hata oluştu.");
-            logger.debug("Agent timeout check failed", err);
         }
-    }
-
-    if (!fs.existsSync(messagesDir)) {
-        UI.success("Henüz işlenecek bir mesaj yok.");
-        return;
-    }
+        if (updatedStatus) {
+            updateDocumentStore("status", agentStatuses);
+            agentStatusCache = { ...agentStatuses }; // Sync cache
+        }
 
-    const messageFiles = fs.readdirSync(messagesDir).filter((f) => f.endsWith(".json"));
-    const pendingMessages: HermesMessage[] = [];
-    const fileMessagesMap: Record<string, HermesMessage[]> = {};
+        if (fs.existsSync(messagesDir)) {
+            const messageFiles = fs.readdirSync(messagesDir).filter((f) => f.endsWith(".json"));
+            const pendingMessages: HermesMessage[] = [];
+            const fileMessagesMap: Record<string, HermesMessage[]> = {};
 
-    for (const file of messageFiles) {
-        const filePath = path.join(messagesDir, file);
-        try {
-            const content = fs.readFileSync(filePath, "utf8").trim();
-            if (!content) continue;
-            const lines = content.split("\n");
-            const allMsgs: HermesMessage[] = [];
-            lines.forEach((line) => {
-                if (!line.trim()) return;
+            for (const file of messageFiles) {
+                const filePath = path.join(messagesDir, file);
                 try {
-                    const parsed = JSON.parse(line);
-                    const msg = HermesMessageSchema.parse(parsed);
-                    if (msg.status === "PENDING") {
-                        pendingMessages.push(msg);
-                    }
-                    allMsgs.push(msg);
-                } catch (e) {
-                    UI.error(`Geçersiz Hermes mesaj formatı atlandı: ${(e as Error).message}`);
+                    const content = fs.readFileSync(filePath, "utf8").trim();
+                    if (!content) continue;
+                    const lines = content.split("\n");
+                    const allMsgs: HermesMessage[] = [];
+                    lines.forEach((line) => {
+                        if (!line.trim()) return;
+                        try {
+                            const parsed = JSON.parse(line);
+                            const msg = HermesMessageSchema.parse(parsed);
+
+                            // Contract Validation
+                            if (msg.category === "ACTION" || msg.category === "DELEGATION") {
+                                try {
+                                    const payload = JSON.parse(msg.content);
+                                    TaskRequestSchema.parse(payload);
+                                } catch (e) {
+                                    UI.error(`Invalid task contract payload: ${(e as Error).message}`);
+                                    return; // Skip invalid message
+                                }
+                            }
+
+                            if (msg.status === "PENDING") {
+                                pendingMessages.push(msg);
+                            }
+                            allMsgs.push(msg);
+                        } catch (e) {
+                            UI.error(`Skipping invalid Hermes message format: ${(e as Error).message}`);
+                        }
+                    });
+                    fileMessagesMap[file] = allMsgs;
+                } catch (err) {
+                    UI.error(`Error occurred while reading ${file}.`);
+                    logger.debug(`Failed to read message file ${file}`, err);
                 }
-            });
-            fileMessagesMap[file] = allMsgs;
-        } catch (err) {
-            UI.error(`${file} mesajı okunurken hata oluştu.`);
-            logger.debug(`Failed to read message file ${file}`, err);
-        }
-    }
+            }
 
-    if (pendingMessages.length === 0) {
-        UI.success("Tüm mesajlar işlenmiş, bekleyen görev yok.");
-        return;
-    }
+            if (pendingMessages.length > 0) {
+                // Sort by priority: HIGH -> NORMAL -> LOW
+                const priorityOrder = { HIGH: 1, NORMAL: 2, LOW: 3 };
+                pendingMessages.sort((a, b) => {
+                    const pA = priorityOrder[a.priority || "NORMAL"] || 2;
+                    const pB = priorityOrder[b.priority || "NORMAL"] || 2;
+                    if (pA !== pB) return pA - pB;
+                    return Date.parse(a.timestamp) - Date.parse(b.timestamp);
+                });
 
-    // Sort by priority: HIGH -> NORMAL -> LOW
-    const priorityOrder = { HIGH: 1, NORMAL: 2, LOW: 3 };
-    pendingMessages.sort((a, b) => {
-        const pA = priorityOrder[a.priority || "NORMAL"] || 2;
-        const pB = priorityOrder[b.priority || "NORMAL"] || 2;
-        if (pA !== pB) return pA - pB;
-        return Date.parse(a.timestamp) - Date.parse(b.timestamp);
-    });
+                UI.intent("Multi-Agent Orchestration", `${pendingMessages.length} pending tasks and collaboration messages found.`);
 
-    UI.intent("Multi-Agent Orkestrasyonu", `${pendingMessages.length} adet bekleyen görev ve işbirliği mesajı bulundu.`);
+                const statusChanges: Record<string, { state: string; task: string }> = {};
 
-    for (const msg of pendingMessages) {
-        const { from, to, content, traceId, category, parentId } = msg;
+                for (const msg of pendingMessages) {
+                    const { from, to, content, traceId, category, parentId } = msg;
 
-        // Visual distinction for Sub-tasks
-        const isSubtask = category === "SUBTASK" || !!parentId;
-        const agentLabel = isSubtask ? `${to} (Sub-Agent)` : to;
+                    const isSubtask = category === "SUBTASK" || !!parentId;
+                    const agentLabel = isSubtask ? `${to} (Sub-Agent)` : to;
 
-        UI.agentBox(agentLabel, content, `Trace: ${traceId} | From: ${from} | Category: ${category}`);
+                    UI.agentBox(agentLabel, content, `Trace: ${traceId} | From: ${from} | Category: ${category}`);
 
-        let targetState = "EXECUTING";
-        if (category === "DELEGATION" || category === "SUBTASK") targetState = "BRIEFED";
+                    let targetState = "EXECUTING";
+                    if (category === "DELEGATION" || category === "SUBTASK") targetState = "BRIEFED";
 
-        transitionAgentState(to, targetState, content);
+                    let taskDescription = content;
+                    if (category === "DELEGATION" || category === "ACTION") {
+                        try {
+                            const payload = JSON.parse(content);
+                            taskDescription = payload.task || content;
+                        } catch {
+                            // Ignore
+                        }
+                    }
 
-        if (targetState === "BRIEFED") {
-            UI.success(`${to} bilgilendirildi ve görevi devraldı.`);
-            transitionAgentState(to, "EXECUTING", content);
-        }
+                    statusChanges[to] = { state: targetState, task: taskDescription };
 
-        if (isSubtask) {
-            UI.success(`Alt görev bağlantısı kuruldu (Parent: ${parentId || "Unknown"}).`);
-        }
+                    if (targetState === "BRIEFED") {
+                        UI.success(`${to} informed and took over the task.`);
+                        statusChanges[to] = { state: "EXECUTING", task: taskDescription };
+                    }
 
-        UI.success(`İşbirliği başlatıldı: ${from} -> ${to}`);
-        console.warn(chalk.gray(`  👉 Talimatlar: ${frameworkDir}/agents/${to.replace("@", "")}.md`));
+                    if (isSubtask) {
+                        UI.success(`Sub-task connection established (Parent: ${parentId || "Unknown"}).`);
+                    }
 
-        // Mark message as processed
-        msg.status = "PROCESSED";
-    }
+                    UI.success(`Collaboration initiated: ${from} -> ${to}`);
+                    console.warn(chalk.gray(`  👉 Instructions: ${frameworkDir}/agents/${to.replace("@", "")}.md`));
 
-    // Write back updated message statuses to files and archive processed messages
-    const archiveDir = path.join(messagesDir, "archive");
-    
-    for (const file of Object.keys(fileMessagesMap)) {
-        const filePath = path.join(messagesDir, file);
-        const msgs = fileMessagesMap[file];
-        
-        const activeMsgs = msgs.filter(m => m.status !== "PROCESSED");
-        const processedMsgs = msgs.filter(m => m.status === "PROCESSED");
-        
-        try {
-            // Write remaining active messages
-            if (activeMsgs.length > 0) {
-                const updatedContent = activeMsgs.map(m => JSON.stringify(m)).join("\n") + "\n";
-                fs.writeFileSync(filePath, updatedContent, "utf8");
-            } else {
-                // Empty the file if no active messages
-                if (fs.existsSync(filePath)) {
-                    fs.writeFileSync(filePath, "", "utf8");
+                    msg.status = "PROCESSED";
                 }
-            }
 
-            // Archive processed messages
-            if (processedMsgs.length > 0) {
-                if (!fs.existsSync(archiveDir)) {
-                    fs.mkdirSync(archiveDir, { recursive: true });
+                applyBatchStatusUpdates(statusChanges);
+
+                const archiveDir = path.join(messagesDir, "archive");
+                
+                for (const file of Object.keys(fileMessagesMap)) {
+                    const filePath = path.join(messagesDir, file);
+                    const msgs = fileMessagesMap[file];
+                    
+                    const activeMsgs = msgs.filter(m => m.status !== "PROCESSED");
+                    const processedMsgs = msgs.filter(m => m.status === "PROCESSED");
+                    
+                    try {
+                        if (activeMsgs.length > 0) {
+                            const updatedContent = activeMsgs.map(m => JSON.stringify(m)).join("\n") + "\n";
+                            writeTextFile(filePath, updatedContent);
+                        } else if (fs.existsSync(filePath)) {
+                            writeTextFile(filePath, "");
+                        }
+
+                        if (processedMsgs.length > 0) {
+                            if (!fs.existsSync(archiveDir)) {
+                                fs.mkdirSync(archiveDir, { recursive: true });
+                            }
+                            const agentName = file.replace(".json", "");
+                            const archivePath = path.join(archiveDir, `${agentName}_archive.json`);
+                            const archiveContent = processedMsgs.map(m => JSON.stringify(m)).join("\n") + "\n";
+                            appendFile(archivePath, archiveContent);
+                            UI.success(`Archived ${processedMsgs.length} messages for @${agentName}`);
+                        }
+                    } catch (err) {
+                        UI.error(`Error occurred while updating and archiving the message file ${file}.`);
+                        logger.debug(`Failed to update and archive message file ${file}`, err);
+                    }
                 }
-                const agentName = file.replace(".json", "");
-                const archivePath = path.join(archiveDir, `${agentName}_archive.json`);
-                const archiveContent = processedMsgs.map(m => JSON.stringify(m)).join("\n") + "\n";
-                fs.appendFileSync(archivePath, archiveContent, "utf8");
-                UI.success(`Archived ${processedMsgs.length} messages for @${agentName}`);
             }
-        } catch (err) {
-            UI.error(`${file} mesaj dosyası güncellenirken ve arşivlenirken hata oluştu.`);
-            logger.debug(`Failed to update and archive message file ${file}`, err);
         }
+
+        // Prevent 100% CPU and provide breathing room for I/O
+        await sleep(2000);
     }
 }
 
@@ -209,14 +230,15 @@ export async function sendMessage(args: {
     const messagePath = path.join(messagesDir, `${agentName}.json`);
     const lockPath = path.join(messagesDir, `${agentName}.lock`);
 
-    let retries = 3;
+    let retries = 20; // Increased retries from 3 to 20
     let acquired = false;
     while (retries > 0) {
         try {
             if (fs.existsSync(lockPath)) {
                 try {
                     const stats = fs.statSync(lockPath);
-                    if (Date.now() - stats.mtimeMs > 5000) {
+                    // Increased stale lock timeout from 5s to 10s for heavy ops
+                    if (Date.now() - stats.mtimeMs > 10000) {
                         fs.unlinkSync(lockPath);
                     }
                 } catch (err) {
@@ -234,17 +256,19 @@ export async function sendMessage(args: {
             if (error.code === "EEXIST") {
                 retries--;
                 if (retries > 0) {
+                    // Exponential backoff or jitter could be added here, 
+                    // but fixed 500ms is usually fine for local file locks.
                     await new Promise((resolve) => setTimeout(resolve, 500));
                 }
             } else {
-                UI.error(`Kilit alınırken beklenmedik hata oluştu: ${error.message || String(err)}`);
+                UI.error(`Unexpected error occurred while acquiring the lock: ${error.message || String(err)}`);
                 break;
             }
         }
     }
 
     if (!acquired) {
-        UI.error(`Mesaj iletilemedi: Hermes kilidi meşgul. (${args.from} -> ${args.to})`);
+        UI.error(`Message could not be delivered: Hermes lock is busy. (${args.from} -> ${args.to})`);
         return;
     }
 
@@ -257,18 +281,11 @@ export async function sendMessage(args: {
             status: "PENDING"
         };
         
-        fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
-        
-        // Log collaboration to audit log
-        const auditPath = path.join(frameworkDir, "observability/audit_log.md");
-        if (fs.existsSync(auditPath)) {
-            const logEntry = `\n- **[${message.timestamp}]** ${args.from} -> ${args.to} | ${args.category} | Priority: ${message.priority} | Trace: ${args.traceId}`;
-            fs.appendFileSync(auditPath, logEntry);
-        }
+        appendFile(messagePath, JSON.stringify(message) + "\n");
         
         return message;
     } catch (err) {
-        UI.error(`Mesaj iletilemedi: ${args.from} -> ${args.to}`);
+        UI.error(`Message could not be delivered: ${args.from} -> ${args.to}`);
         logger.debug(`Hermes sendMessage failed (${args.from} -> ${args.to})`, err);
     } finally {
         if (acquired && fs.existsSync(lockPath)) {
@@ -281,29 +298,21 @@ export async function sendMessage(args: {
     }
 }
 
-function transitionAgentState(agent: string, state: string, task: string) {
-    const frameworkDir = getFrameworkDir();
-    const statusPath = path.join(frameworkDir, "STATUS.md");
-    if (!fs.existsSync(statusPath)) return;
-    try {
-        const content = fs.readFileSync(statusPath, "utf8");
-        const lines = content.split("\n");
-        const targetName = agent.startsWith("@") ? agent : `@${agent}`;
-        const newLines = lines.map(line => {
-            if (line.includes(`| ${targetName} |`)) {
-                const parts = line.split("|");
-                if (parts.length >= 7) {
-                    parts[2] = ` ${state} `;
-                    parts[3] = ` ${task.slice(0, 25)}... `;
-                    parts[4] = ` ${new Date().toISOString()} `;
-                    return parts.join("|");
-                }
-            }
-            return line;
-        });
-        fs.writeFileSync(statusPath, newLines.join("\n"));
-    } catch (err) {
-        UI.error("STATUS.md güncellenemedi.");
-        logger.debug(`Failed to transition agent state for ${agent}`, err);
+
+function applyBatchStatusUpdates(changes: Record<string, { state: string; task: string }>) {
+    let hasChanges = false;
+    const now = new Date().toISOString();
+
+    for (const [agent, data] of Object.entries(changes)) {
+        const current = agentStatusCache[agent];
+        if (!current || current.state !== data.state || current.task !== data.task) {
+            agentStatusCache[agent] = { ...data, lastUpdated: now };
+            hasChanges = true;
+        }
+    }
+
+    if (hasChanges) {
+        updateDocumentStore("status", agentStatusCache);
+        logger.debug("In-memory status cache synced to disk.");
     }
 }

package/src/cli/commands/plan.ts

@@ -0,0 +1,47 @@
+import fs from "fs";
+import path from "path";
+import { updateDocumentStore } from "../utils/memory.js";
+import { generateULID } from "../utils/time.js";
+import { UI } from "../utils/ui.js";
+
+/**
+ * Parses docs/user/roadmap.md and injects tasks into the Document Store.
+ */
+export async function planCommand() {
+    const projectRoot = process.cwd();
+    const roadmapPath = path.join(projectRoot, "docs/user/roadmap.md");
+
+    if (!fs.existsSync(roadmapPath)) {
+        UI.error("Roadmap file not found at docs/user/roadmap.md");
+        return;
+    }
+
+    const content = fs.readFileSync(roadmapPath, "utf8");
+    const taskRegex = /- \[ \] (.*) \| (.*) \| (.*)/g;
+    let match;
+    let count = 0;
+
+    UI.intent("Planning Engine", "Parsing roadmap.md and injecting tasks into Document Store...");
+
+    while ((match = taskRegex.exec(content)) !== null) {
+        const description = match[1];
+        const priority = match[2];
+        const agent = match[3];
+        const traceId = generateULID();
+        
+        const taskData = {
+            traceId,
+            description: description.trim(),
+            priority: priority.trim(),
+            agent: agent.trim().replace("@", ""),
+            status: "PENDING",
+            createdAt: new Date().toISOString()
+        };
+
+        updateDocumentStore("task", taskData, traceId);
+        UI.success(`Injected task: ${taskData.description} (Agent: ${taskData.agent})`);
+        count++;
+    }
+
+    UI.success(`Plan complete: ${count} tasks injected into Document Store.`);
+}

package/src/cli/commands/script.ts

@@ -4,7 +4,7 @@ import cp from "child_process";
 
 const targetDir = process.cwd(); // Assuming targetDir is process.cwd() in the CLI context
 
-export function runScriptCommand(script: string, projectPath: string) {
+export async function runScriptCommand(script: string, projectPath: string) {
     const fullPath = path.join(targetDir, projectPath);
     if (!fs.existsSync(fullPath)) {
         console.warn(`❌ Project path not found: ${projectPath}`);

package/src/cli/commands/security.ts

@@ -5,7 +5,7 @@ import { collectFiles } from "../utils/fs.js";
 
 const targetDir = process.cwd();
 
-export function securityAuditCommand(targetPath: string) {
+export async function securityAuditCommand(targetPath: string) {
     console.warn(`🔍 Running Advanced Security Audit on: ${targetPath}...`);
     const scanRules = [
         { pattern: /sql`/, message: "Potential Raw SQL usage detected", severity: "HIGH" },