agent-enderun 0.6.0 → 0.6.5

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

@@ -145,7 +145,7 @@ export const codebaseHandlers = {
             let queryRegex: RegExp;
             try {
                 queryRegex = new RegExp(query, "i");
-            } catch (error) {
+            } catch {
                 return { content: [{ type: "text", text: "Invalid regex pattern in query." }] };
             }
             const matches: string[] = [];
@@ -164,7 +164,7 @@ export const codebaseHandlers = {
                 }
             }
             return { content: [{ type: "text", text: matches.join("\n") || "No matches found." }] };
-        } catch (error) {
+        } catch {
             return { content: [{ type: "text", text: "Search failed." }] };
         }
     },
@@ -223,7 +223,7 @@ export const codebaseHandlers = {
                 });
             }
             return { content: [{ type: "text", text: `### CODEBASE INTELLIGENCE REPORT\n\n**Complexity Spikes (>300 lines):**\n${complexitySpikes.length > 0 ? complexitySpikes.map(s => `- ${s}`).join("\n") : "- None detected"}\n\n**Potential Dead Code (Unused Exports):**\n${potentialDeadCode.length > 0 ? potentialDeadCode.map(d => `- ${d}`).join("\n") : "- None detected (within scanned scope)"}` }] };
-        } catch (error) {
+        } catch {
             return { content: [{ type: "text", text: "Intelligence scan failed." }] };
         }
     },
@@ -247,8 +247,8 @@ export const codebaseHandlers = {
             const referenceFunctions = referenceFile.getFunctions().map(f => f.getName());
             if (referenceFunctions.some(f => f?.startsWith("get")) && !targetFunctions.some(f => f?.startsWith("get"))) deviations.push("Reference uses 'get' prefix for functions, target does not.");
             return { content: [{ type: "text", text: deviations.length > 0 ? `### PROCEDURAL CONTINUITY DEVIATIONS\n\n${deviations.map(d => `- ${d}`).join("\n")}` : "No major structural or stylistic deviations detected based on reference." }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Continuity analysis failed." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Dependency analysis failed." }] };
         }
     },
     generate_dependency_graph: async (args: unknown, projectRoot: string) => {
@@ -277,7 +277,7 @@ export const codebaseHandlers = {
             if (uniqueEdges.length === 0) return { content: [{ type: "text", text: "No internal dependencies found in the scanned path." }] };
             mermaid += uniqueEdges.join("\n");
             return { content: [{ type: "text", text: `### VISUAL ARCHITECTURE MAP: ${targetPath}\n\n\`\`\`mermaid\n${mermaid}\n\`\`\`\n\n**Total Nodes:** ${new Set(edges.flatMap(e => [e.from, e.to])).size} | **Total Edges:** ${uniqueEdges.length}` }] };
-        } catch (error) {
+        } catch {
             return { content: [{ type: "text", text: "Dependency graph generation failed." }] };
         }
     },

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

@@ -45,6 +45,23 @@ export const contractTools = [
             required: ["domain"],
         },
     },
+    {
+        name: "validate_frontend_api_contract",
+        description: "Scans frontend hooks for API calls and compares them against backend API documentation and contracts. Returns mismatches (missing endpoints, type issues, etc.).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                frontendHooksPath: {
+                    type: "string",
+                    description: "Relative path to frontend hooks directory (default: apps/web/src/pages)",
+                },
+                backendApiDocsPath: {
+                    type: "string",
+                    description: "Relative path to backend API documentation (default: docs/api)",
+                },
+            },
+        },
+    },
 ];
 
 export const contractHandlers = {
@@ -56,8 +73,8 @@ export const contractHandlers = {
             const currentHash = calculateContractHash(sharedTypesDir, projectRoot);
             const storedHash = JSON.parse(fs.readFileSync(contractJsonPath, "utf-8")).contract_hash;
             return { content: [{ type: "text", text: currentHash === storedHash ? "✅ MATCH: Contract is valid and synchronized." : `❌ MISMATCH: Current hash (${currentHash.slice(0, 8)}...) does not match stored hash (${storedHash.slice(0, 8)}...).` }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Failed to verify contract." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Contract integrity check failed." }] };
         }
     },
     update_contract_hash: async (args: unknown, projectRoot: string) => {
@@ -73,7 +90,7 @@ export const contractHandlers = {
             contractJson.last_updated = new Date().toISOString();
             fs.writeFileSync(contractJsonPath, JSON.stringify(contractJson, null, 2));
             return { content: [{ type: "text", text: `SUCCESS: Contract hash updated to ${currentHash}` }] };
-        } catch (error) {
+        } catch {
             return { content: [{ type: "text", text: "Failed to update contract hash." }] };
         }
     },
@@ -104,8 +121,101 @@ export const contractHandlers = {
             });
 
             return { content: [{ type: "text", text: `### CONTRACT INTEGRITY SHIELD: ${parsed.data.domain.toUpperCase()}\n\n` + `- **Missing/Undefined Types:** ${missingTypes.length > 0 ? `⚠️ ${missingTypes.join(", ")}` : "✅ All types synchronized"}\n\n` + `**Result:** ${missingTypes.length === 0 ? "PASSED" : "FAILED"}` }] };
-        } catch (error) {
+        } catch {
             return { content: [{ type: "text", text: "Contract verification failed." }] };
         }
     },
+
+    validate_frontend_api_contract: async (args: unknown, projectRoot: string) => {
+        const a = args as Record<string, string> | undefined;
+        const frontendPath = a?.frontendHooksPath || "apps/web/src/pages";
+        const backendDocsPath = a?.backendApiDocsPath || "docs/api";
+
+        try {
+            const fullFrontendPath = path.join(projectRoot, frontendPath);
+            const fullBackendDocsPath = path.join(projectRoot, backendDocsPath);
+
+            if (!fs.existsSync(fullFrontendPath)) {
+                return { content: [{ type: "text", text: `Frontend hooks path not found: ${frontendPath}` }] };
+            }
+
+            const hookFiles = collectFilesRecursively(fullFrontendPath, new Set(["ts", "tsx"]));
+            const apiCalls: { endpoint: string; responseType?: string }[] = [];
+
+            // Hook dosyalarındaki fetch çağrılarını ve response tiplerini çıkar
+            for (const file of hookFiles) {
+                const content = fs.readFileSync(file, "utf-8");
+
+                // Basit regex ile endpoint + response tipi yakala
+                const matches = content.matchAll(
+                    /(?:const\s+\w+\s*[:=]\s*await\s+)?fetch\(['"`](\/api\/[^'"`]+)['"`][^)]*\)\s*(?:\.then[^;]+)?(?:\s*as\s+([A-Z][a-zA-Z0-9]+)|:\s*([A-Z][a-zA-Z0-9]+))?/g
+                );
+
+                for (const match of matches) {
+                    const endpoint = match[1];
+                    const responseType = match[2] || match[3];
+                    apiCalls.push({ endpoint, responseType });
+                }
+            }
+
+            const uniqueEndpoints = Array.from(new Set(apiCalls.map(c => c.endpoint)));
+
+            if (!fs.existsSync(fullBackendDocsPath)) {
+                return { content: [{ type: "text", text: `Backend API docs path not found: ${backendDocsPath}` }] };
+            }
+
+            const backendDocFiles = collectFilesRecursively(fullBackendDocsPath, new Set(["md"]));
+            const documentedEndpoints: string[] = [];
+
+            for (const file of backendDocFiles) {
+                const content = fs.readFileSync(file, "utf-8");
+                const matches = content.matchAll(/`?(\/api\/[a-zA-Z0-9/_-]+)`?/g);
+                for (const match of matches) {
+                    documentedEndpoints.push(match[1]);
+                }
+            }
+
+            const missingInDocs = uniqueEndpoints.filter(ep => !documentedEndpoints.some(d => ep.startsWith(d)));
+            const missingInHooks = documentedEndpoints.filter(d => !uniqueEndpoints.some(e => e.startsWith(d)));
+
+            let report = `### FRONTEND ↔ BACKEND CONTRACT VALIDATION REPORT\n\n`;
+            report += `**Scanned Frontend Hooks:** ${uniqueEndpoints.length} unique endpoints found\n`;
+            report += `**Scanned Backend API Docs:** ${documentedEndpoints.length} endpoints documented\n\n`;
+
+            if (missingInDocs.length > 0) {
+                report += `⚠️ **Endpoints called from frontend but NOT documented in backend:**\n${missingInDocs.map(e => `- ${e}`).join("\n")}\n\n`;
+            } else {
+                report += `✅ All frontend-called endpoints are documented in backend.\n\n`;
+            }
+
+            if (missingInHooks.length > 0) {
+                report += `ℹ️ **Endpoints documented in backend but NOT used in scanned frontend hooks:**\n${missingInHooks.map(e => `- ${e}`).join("\n")}\n\n`;
+            }
+
+            // Basit tip karşılaştırması (eğer responseType varsa)
+            const typeMismatches: string[] = [];
+            for (const call of apiCalls) {
+                if (call.responseType) {
+                    const docContent = backendDocFiles
+                        .map(f => fs.readFileSync(f, "utf-8"))
+                        .join("\n");
+
+                    if (!docContent.includes(call.responseType)) {
+                        typeMismatches.push(`${call.endpoint} → expected type "${call.responseType}" not found in docs`);
+                    }
+                }
+            }
+
+            if (typeMismatches.length > 0) {
+                report += `⚠️ **Potential Type Mismatches:**\n${typeMismatches.map(m => `- ${m}`).join("\n")}\n\n`;
+            }
+
+            report += `**Result:** ${missingInDocs.length === 0 && typeMismatches.length === 0 ? "PASSED" : "FAILED (see mismatches above)"}`;
+
+            return { content: [{ type: "text", text: report }] };
+        } catch (err: unknown) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { content: [{ type: "text", text: `Validation failed: ${message}` }] };
+        }
+    },
 };

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

@@ -42,7 +42,7 @@ export const databaseHandlers = {
             }
             if (tablesFound === 0) return { content: [{ type: "text", text: "No database tables detected." }] };
             return { content: [{ type: "text", text: `### DATABASE SCHEMA MAP\n\n\`\`\`mermaid\n${mermaid}\n\`\`\`\n\n**Total Tables Detected:** ${tablesFound}` }] };
-        } catch (error) {
+        } catch {
             return { content: [{ type: "text", text: "Database schema analysis failed." }] };
         }
     },

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

@@ -6,7 +6,7 @@ import {
     collectMarkdownArtifacts, 
     FRAMEWORK_VERSION 
 } from "../utils.js";
-import { VERIFY_FRAMEWORK_HEALTH_ARGS_SCHEMA } from "../schemas.js";
+
 
 export const frameworkTools = [
     {
@@ -72,15 +72,13 @@ export const frameworkHandlers = {
                 if (allDeps.includes("typescript")) detected.push("TypeScript");
                 if (detected.length > 0) techStack = detected.join(", ");
             }
-            const rootDirs = fs.readdirSync(projectRoot).filter(f => fs.lstatSync(path.join(projectRoot, f)).isDirectory() && !f.startsWith("."));
-            const isMonorepo = rootDirs.includes("apps") || rootDirs.includes("packages");
             const date = new Date().toISOString().split("T")[0];
             const bootstrapContent = `# PROJECT MEMORY — Legacy Onboarding\n\n## CURRENT STATUS\n\n| Active Phase | Profile | Last Update | Active Trace ID | Blockers |\n| PHASE_1 | Full | ${date} | — | Legacy Onboarding |`;
             if (fs.existsSync(memoryPath)) fs.copyFileSync(memoryPath, memoryPath + ".bak");
             fs.writeFileSync(memoryPath, bootstrapContent);
             return { content: [{ type: "text", text: `Legacy Codebase Bootstrap complete. Detected Stack: ${techStack}.` }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Failed to bootstrap legacy memory." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to get project gaps." }] };
         }
     },
     get_framework_status: async (args: unknown, projectRoot: string) => {
@@ -94,8 +92,8 @@ export const frameworkHandlers = {
             return {
                 content: [{ type: "text", text: `Framework active (v${FRAMEWORK_VERSION}). Phase: ${phase}. Profile: ${profile}.` }],
             };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Framework active. Memory unreadable." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to get memory insights." }] };
         }
     },
     get_project_gaps: async (args: unknown, projectRoot: string) => {
@@ -147,8 +145,8 @@ export const frameworkHandlers = {
             return {
                 content: [{ type: "text", text: `### LIVE MEMORY INSIGHTS\n\n**Active Tasks:**\n${activeTasks.trim()}\n\n**Recent History:**\n${history.trim().substring(0, 1000)}...\n\n**Brain Snapshot:**\n${dashboardAgents.trim().substring(0, 500)}...` }],
             };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Failed to gather memory insights." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to get framework status." }] };
         }
     },
     codebase_context: async (args: unknown, projectRoot: string) => {
@@ -160,15 +158,14 @@ export const frameworkHandlers = {
             return {
                 content: [{ type: "text", text: "### CONTEXT ARTIFACTS\n\n" + `PROJECT_MEMORY: ${fs.existsSync(memoryPath) ? "present" : "missing"}\n` + `BRAIN_DASHBOARD: ${fs.existsSync(dashboardPath) ? "present" : "missing"}\n` + `Docs:\n${artifacts.length > 0 ? artifacts.join("\n") : "No markdown artifacts found."}` }],
             };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Context discovery failed." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to bootstrap legacy memory." }] };
         }
     },
     get_system_time: async () => {
         return { content: [{ type: "text", text: new Date().toISOString() }] };
     },
     verify_framework_health: async (args: unknown, projectRoot: string) => {
-        const parsed = VERIFY_FRAMEWORK_HEALTH_ARGS_SCHEMA.safeParse(args ?? {});
         try {
             // Run the internal CLI check command via tsx to ensure we test current state
             // If the CLI is not yet linked, we might need a relative path

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

@@ -35,8 +35,8 @@ export const gitHandlers = {
             else if (files.some(f => f.includes("framework-mcp"))) scope = "mcp";
             const summary = files.length === 1 ? `update ${path.basename(files[0])}` : `update ${files.length} files`;
             return { content: [{ type: "text", text: `### SUGGESTED SEMANTIC COMMIT MESSAGE\n\n\`[${parsed.data.traceId}] ${type}(${scope}): ${summary}\`\n\n**Files Analyzed:**\n${files.map(f => `- ${f}`).join("\n")}` }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Failed to generate commit message." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to generate semantic commit message." }] };
         }
     },
 };

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

@@ -3,8 +3,7 @@ import path from "path";
 import { getFrameworkDir } from "../utils.js";
 import { 
     SEARCH_KNOWLEDGE_BASE_ARGS_SCHEMA, 
-    UPDATE_KNOWLEDGE_BASE_ARGS_SCHEMA,
-    GET_KNOWLEDGE_GRAPH_ARGS_SCHEMA
+    UPDATE_KNOWLEDGE_BASE_ARGS_SCHEMA
 } from "../schemas.js";
 
 export const knowledgeTools = [
@@ -82,7 +81,7 @@ function parseFrontmatter(content: string) {
             }).filter(Boolean);
 
             return { content: [{ type: "text", text: results.length > 0 ? `### KNOWLEDGE BASE SEARCH RESULTS\n\n${results.join("\n\n---\n\n")}` : "No matching knowledge entries found." }] };
-        } catch (error) {
+        } catch {
             return { content: [{ type: "text", text: "Knowledge base search failed." }] };
         }
     },
@@ -105,7 +104,7 @@ function parseFrontmatter(content: string) {
 
             fs.writeFileSync(path.join(kbDir, fileName), finalContent);
             return { content: [{ type: "text", text: `Obsidian Wiki updated: ${parsed.data.topic}` }] };
-        } catch (error) {
+        } catch {
             return { content: [{ type: "text", text: "Failed to update knowledge base." }] };
         }
     },
@@ -135,8 +134,8 @@ function parseFrontmatter(content: string) {
             });
 
             return { content: [{ type: "text", text: `### KNOWLEDGE GRAPH (Mermaid)\n\n\`\`\`mermaid\n${mermaid}\n\`\`\`` }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Failed to generate knowledge graph." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to get knowledge graph." }] };
         }
     }
 };

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

@@ -59,7 +59,7 @@ export const memoryHandlers = {
                         memoryContent = prependToSection(memoryContent, h, content);
                         updated = true;
                         break;
-                    } catch (e) {
+                    } catch {
                         // Ignore section not found
                     }
                 }
@@ -72,9 +72,8 @@ export const memoryHandlers = {
             fs.writeFileSync(memoryPath, memoryContent);
             if (fs.existsSync(lockPath) && fs.readFileSync(lockPath, "utf-8").includes(lockOwner)) fs.unlinkSync(lockPath);
             return { content: [{ type: "text", text: `Section ${section} updated successfully.` }] };
-        } catch (error) {
-            if (fs.existsSync(lockPath) && fs.readFileSync(lockPath, "utf-8").includes(lockOwner)) fs.unlinkSync(lockPath);
-            return { content: [{ type: "text", text: `Memory update failed: ${error instanceof Error ? error.message : "Unknown error"}` }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to read project memory." }] };
         }
     },
     read_project_memory: async (args: unknown, projectRoot: string) => {
@@ -83,8 +82,8 @@ export const memoryHandlers = {
             const memoryPath = path.join(projectRoot, frameworkDir, "PROJECT_MEMORY.md");
             if (!fs.existsSync(memoryPath)) return { content: [{ type: "text", text: `ERROR: ${frameworkDir}/PROJECT_MEMORY.md not found.` }] };
             return { content: [{ type: "text", text: fs.readFileSync(memoryPath, "utf-8") }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "ERROR: Failed to read PROJECT_MEMORY.md" }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to update project memory." }] };
         }
     },
 };

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

@@ -4,24 +4,26 @@ import { getFrameworkDir } from "../utils.js";
 import { 
     SEND_AGENT_MESSAGE_ARGS_SCHEMA, 
     READ_AGENT_MESSAGES_ARGS_SCHEMA,
-    GET_AGENT_INBOX_STATS_ARGS_SCHEMA
+    GET_AGENT_INBOX_STATS_ARGS_SCHEMA,
+    UPDATE_AGENT_MESSAGE_STATUS_ARGS_SCHEMA
 } from "../schemas.js";
 
 export const messageTools = [
     {
         name: "send_agent_message",
         description: "Sends a message to another specialized agent following the Hermes Protocol.",
-        inputSchema: {
-            type: "object",
-            properties: {
-                to: { type: "string", description: "Recipient agent name" },
-                message: { type: "string", description: "The message content" },
-                traceId: { type: "string", description: "The active Trace ID" },
-                category: { type: "string", enum: ["ACTION", "DELEGATION", "INFO", "ALERT"], default: "INFO" },
-                priority: { type: "string", enum: ["LOW", "MEDIUM", "HIGH", "URGENT"], default: "MEDIUM" },
+            inputSchema: {
+                type: "object",
+                properties: {
+                    from: { type: "string", description: "Sender agent name (e.g. @manager, @backend)" },
+                    to: { type: "string", description: "Recipient agent name" },
+                    message: { type: "string", description: "The message content" },
+                    traceId: { type: "string", description: "The active Trace ID" },
+                    category: { type: "string", enum: ["ACTION", "DELEGATION", "INFO", "ALERT"], default: "INFO" },
+                    priority: { type: "string", enum: ["LOW", "MEDIUM", "HIGH", "URGENT"], default: "MEDIUM" },
+                },
+                required: ["from", "to", "message", "traceId"],
             },
-            required: ["to", "message", "traceId"],
-        },
     },
     {
         name: "read_agent_messages",
@@ -46,16 +48,30 @@ export const messageTools = [
             required: ["agent"],
         },
     },
+    {
+        name: "update_agent_message_status",
+        description: "Allows an agent to acknowledge, complete, or reject a Hermes message by Trace ID (advances the orchestration lifecycle).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent: { type: "string", description: "The agent performing the status update" },
+                traceId: { type: "string", description: "Trace ID of the message to update" },
+                newStatus: { type: "string", enum: ["ACKNOWLEDGED", "COMPLETED", "REJECTED"], description: "New lifecycle status" },
+            },
+            required: ["agent", "traceId", "newStatus"],
+        },
+    },
 ];
 
 interface Message {
     timestamp: string;
     from: string;
+    to: string;
     traceId: string;
     category: "ACTION" | "DELEGATION" | "INFO" | "ALERT";
     priority: "LOW" | "MEDIUM" | "HIGH" | "URGENT";
     content: string;
-    read: boolean;
+    status: "PENDING" | "READ" | "ACKNOWLEDGED" | "COMPLETED" | "REJECTED";
 }
 
 function normalizeAgentName(agent: string): string | null {
@@ -75,19 +91,21 @@ export const messageHandlers = {
             if (!fs.existsSync(messagesDir)) fs.mkdirSync(messagesDir, { recursive: true });
             const messagePath = path.join(messagesDir, `${recipient}.json`);
             const messages = (fs.existsSync(messagePath) ? JSON.parse(fs.readFileSync(messagePath, "utf-8")) : []) as Message[];
+            const sender = normalizeAgentName(parsed.data.from) || "unknown";
             messages.push({ 
                 timestamp: new Date().toISOString(), 
-                from: "manager", 
+                from: sender,
+                to: recipient,
                 traceId: parsed.data.traceId, 
                 category: parsed.data.category,
                 priority: parsed.data.priority,
                 content: parsed.data.message, 
-                read: false 
+                status: "PENDING"
             });
             fs.writeFileSync(messagePath, JSON.stringify(messages, null, 2));
             return { content: [{ type: "text", text: `Hermes: Message sent to @${recipient} [${parsed.data.category} | ${parsed.data.priority}].` }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Failed to send message via Hermes." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to send agent message." }] };
         }
     },
     read_agent_messages: async (args: unknown, projectRoot: string) => {
@@ -100,21 +118,30 @@ export const messageHandlers = {
             const messagePath = path.join(projectRoot, frameworkDir, "messages", `${agentName}.json`);
             if (!fs.existsSync(messagePath)) return { content: [{ type: "text", text: "No messages found." }] };
             const messages = JSON.parse(fs.readFileSync(messagePath, "utf-8")) as Message[];
-            const unread = messages.filter((m) => !m.read && (!parsed.data.traceId || m.traceId === parsed.data.traceId));
+            const pending = messages.filter((m) => 
+                (m.status === "PENDING" || m.status === "ACKNOWLEDGED") && 
+                (!parsed.data.traceId || m.traceId === parsed.data.traceId)
+            );
             
-            fs.writeFileSync(messagePath, JSON.stringify(messages.map((m) => (
-                !m.read && (!parsed.data.traceId || m.traceId === parsed.data.traceId) ? { ...m, read: true } : m
-            )), null, 2));
+            // Transition PENDING → READ
+            const updated = messages.map((m) => {
+                if ((m.status === "PENDING" || m.status === "ACKNOWLEDGED") && 
+                    (!parsed.data.traceId || m.traceId === parsed.data.traceId)) {
+                    return { ...m, status: "READ" as const };
+                }
+                return m;
+            });
+            fs.writeFileSync(messagePath, JSON.stringify(updated, null, 2));
             
-            if (unread.length === 0) return { content: [{ type: "text", text: "No new messages." }] };
+            if (pending.length === 0) return { content: [{ type: "text", text: "No new messages." }] };
             
-            const formatted = unread.map((m) => 
+            const formatted = pending.map((m) => 
                 `- [${m.priority}] **${m.from}** (${m.category}): ${m.content} *(Trace: ${m.traceId})*`
             ).join("\n");
             
             return { content: [{ type: "text", text: `### HERMES INBOX: @${agentName}\n\n${formatted}` }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Failed to read messages." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to send agent message." }] };
         }
     },
     get_agent_inbox_stats: async (args: unknown, projectRoot: string) => {
@@ -127,21 +154,60 @@ export const messageHandlers = {
             const messagePath = path.join(projectRoot, frameworkDir, "messages", `${agentName}.json`);
             if (!fs.existsSync(messagePath)) return { content: [{ type: "text", text: "Inbox empty." }] };
             const messages = JSON.parse(fs.readFileSync(messagePath, "utf-8")) as Message[];
-            const unread = messages.filter(m => !m.read);
+            const pendingOrRead = messages.filter(m => m.status === "PENDING" || m.status === "READ");
             
             const priorityDist = messages.reduce((acc, m) => {
                 acc[m.priority] = (acc[m.priority] || 0) + 1;
                 return acc;
             }, {} as Record<string, number>);
 
+            const statusDist = messages.reduce((acc, m) => {
+                acc[m.status] = (acc[m.status] || 0) + 1;
+                return acc;
+            }, {} as Record<string, number>);
+
             return { 
                 content: [{ 
                     type: "text", 
-                    text: `### INBOX STATS: @${agentName}\n- Total: ${messages.length}\n- Unread: ${unread.length}\n- Priority Distribution: ${JSON.stringify(priorityDist)}` 
+                    text: `### INBOX STATS: @${agentName}\n- Total: ${messages.length}\n- Pending/Read: ${pendingOrRead.length}\n- By Priority: ${JSON.stringify(priorityDist)}\n- By Status: ${JSON.stringify(statusDist)}` 
                 }] 
             };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Failed to get inbox stats." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to read agent messages." }] };
+        }
+    },
+
+    update_agent_message_status: async (args: unknown, projectRoot: string) => {
+        const parsed = UPDATE_AGENT_MESSAGE_STATUS_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success) return { content: [{ type: "text", text: "Invalid arguments for status update." }] };
+
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const agentName = normalizeAgentName(parsed.data.agent);
+            if (!agentName) return { content: [{ type: "text", text: "Invalid agent name." }] };
+
+            const messagePath = path.join(projectRoot, frameworkDir, "messages", `${agentName}.json`);
+            if (!fs.existsSync(messagePath)) return { content: [{ type: "text", text: "No messages for this agent." }] };
+
+            const messages = JSON.parse(fs.readFileSync(messagePath, "utf-8")) as Message[];
+
+            let updated = false;
+            const newMessages = messages.map((m) => {
+                if (m.traceId === parsed.data.traceId) {
+                    updated = true;
+                    return { ...m, status: parsed.data.newStatus };
+                }
+                return m;
+            });
+
+            if (!updated) {
+                return { content: [{ type: "text", text: `No message found with Trace ID ${parsed.data.traceId}.` }] };
+            }
+
+            fs.writeFileSync(messagePath, JSON.stringify(newMessages, null, 2));
+            return { content: [{ type: "text", text: `Hermes: Message ${parsed.data.traceId} marked as ${parsed.data.newStatus}.` }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to update message status." }] };
         }
     }
 };

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

@@ -3,8 +3,7 @@ import path from "path";
 import { spawnSync } from "child_process";
 import { Project } from "ts-morph";
 import { 
-    resolveSafePath, 
-    getFrameworkDir 
+    resolveSafePath 
 } from "../utils.js";
 import { 
     VALIDATE_REPOSITORY_HEALTH_ARGS_SCHEMA, 
@@ -69,8 +68,8 @@ export const repositoryHandlers = {
             if (scope === "full" || scope === "test") results.push(runScript("test"));
             if (scope === "full" || scope === "build") results.push(runScript("build"));
             return { content: [{ type: "text", text: `### REPOSITORY HEALTH REPORT\n\n` + results.map(r => `- **${r.name.toUpperCase()}** (${r.script}): ${r.status}${r.status === "FAILED" && r.details ? `\n  ${r.details}` : ""}`).join("\n") }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Health validation failed." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to analyze repository health." }] };
         }
     },
     analyze_documentation_debt: async (args: unknown, projectRoot: string) => {
@@ -95,8 +94,8 @@ export const repositoryHandlers = {
             }
             const majorDirs = ["apps/backend", "apps/web", "framework-mcp"], missingREADME = majorDirs.filter(dir => fs.existsSync(path.join(projectRoot, dir)) && !fs.existsSync(path.join(projectRoot, dir, "README.md")));
             return { content: [{ type: "text", text: `### DOCUMENTATION DEBT REPORT\n\n**Missing JSDoc:**\n${missingJSDoc.slice(0, 10).join("\n")}\n\n**Missing README.md:**\n${missingREADME.join("\n")}` }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Documentation debt scan failed." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Failed to analyze documentation debt." }] };
         }
     },
 };

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

@@ -71,8 +71,9 @@ export const scaffoldHandlers = {
             fs.cpSync(sourceDir, destDir, { recursive: true });
 
             return { content: [{ type: "text", text: `Successfully instantiated blueprint '${blueprintPath}' into '${targetPath}'` }] };
-        } catch (error: any) {
-            return { content: [{ type: "text", text: `Scaffold failed: ${error.message}` }] };
+        } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return { content: [{ type: "text", text: `Scaffold failed: ${message}` }] };
         }
     },
     save_as_blueprint: async (args: unknown, projectRoot: string) => {
@@ -97,8 +98,9 @@ export const scaffoldHandlers = {
             }
 
             return { content: [{ type: "text", text: `Successfully saved blueprint to '${blueprintPath}'` }] };
-        } catch (error: any) {
-            return { content: [{ type: "text", text: `Failed to save blueprint: ${error.message}` }] };
+        } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return { content: [{ type: "text", text: `Failed to save blueprint: ${message}` }] };
         }
     },
     list_blueprints: async (args: unknown, projectRoot: string) => {
@@ -140,8 +142,9 @@ export const scaffoldHandlers = {
             available = Array.from(new Set(available));
 
             return { content: [{ type: "text", text: `### AVAILABLE BLUEPRINTS\n\n` + available.map(b => `- ${b}`).join("\n") }] };
-        } catch (error: any) {
-            return { content: [{ type: "text", text: `Listing blueprints failed: ${error.message}` }] };
+        } catch (error: unknown) {
+            const message = error instanceof Error ? error.message : "Unknown error";
+            return { content: [{ type: "text", text: `Listing blueprints failed: ${message}` }] };
         }
     },
 };

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

@@ -82,8 +82,8 @@ export const securityHandlers = {
                 });
             }
             return { content: [{ type: "text", text: vulnerabilities.length > 0 ? `### ADVANCED SECURITY AUDIT RESULTS\n\n${Array.from(new Set(vulnerabilities)).join("\n\n")}` : "No security patterns or rule violations detected (Regex & AST verified)." }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Security scan failed." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Security audit failed." }] };
         }
     },
     analyze_constitution_compliance: async (args: unknown, projectRoot: string) => {
@@ -136,8 +136,8 @@ export const securityHandlers = {
             }
 
             return { content: [{ type: "text", text: `### CONSTITUTION COMPLIANCE REPORT\n\n` + (violations.length > 0 ? `⚠️ **VIOLATIONS FOUND:**\n${violations.map(v => `- ${v}`).join("\n")}` : "✅ **ALL SYSTEMS COMPLIANT:** AST and Regex scans passed. No rule violations detected.") }] };
-        } catch (error) {
-            return { content: [{ type: "text", text: "Compliance analysis failed." }] };
+        } catch {
+            return { content: [{ type: "text", text: "Constitution compliance check failed." }] };
         }
     },
 };