agent-enderun 0.1.10 → 0.2.1

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

@@ -0,0 +1,49 @@
+import fs from "fs";
+import path from "path";
+import { Project } from "ts-morph";
+import { resolveSafePath } from "../utils.js";
+import { ANALYZE_DATABASE_SCHEMA_ARGS_SCHEMA } from "../schemas.js";
+
+export const databaseTools = [
+    {
+        name: "analyze_database_schema",
+        description: "Scans the backend codebase (e.g., Kysely migrations or Prisma schemas) to extract and visualize the database schema as a Mermaid ER diagram.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to scan for DB definitions", default: "apps/backend" },
+            },
+        },
+    },
+];
+
+export const databaseHandlers = {
+    analyze_database_schema: async (args: any, projectRoot: string) => {
+        const parsed = ANALYZE_DATABASE_SCHEMA_ARGS_SCHEMA.safeParse(args ?? {});
+        const targetPath = parsed.success ? parsed.data.path : "apps/backend";
+        try {
+            const safeTargetPath = resolveSafePath(projectRoot, targetPath);
+            if (!fs.existsSync(safeTargetPath)) return { content: [{ type: "text", text: "Database path not found." }] };
+            const tsProject = new Project();
+            tsProject.addSourceFilesAtPaths(path.join(safeTargetPath, "**/*.{ts,tsx}"));
+            let mermaid = "erDiagram\n", tablesFound = 0;
+            for (const sourceFile of tsProject.getSourceFiles()) {
+                const text = sourceFile.getFullText();
+                const tableMatches = Array.from(text.matchAll(/\.createTable\(['"]([^'"]+)['"]\)/g));
+                for (const match of tableMatches) {
+                    const tableName = match[1]; tablesFound++;
+                    mermaid += `  ${tableName} {\n`;
+                    const colRegex = /\.addColumn\(['"]([^'"]+)['"]\s*,\s*['"]([^'"]+)['"]/g;
+                    let colMatch; while ((colMatch = colRegex.exec(text)) !== null) {
+                        mermaid += `    ${colMatch[2].replace(/[^a-zA-Z0-9]/g, '_')} ${colMatch[1]}\n`;
+                    }
+                    mermaid += `  }\n`;
+                }
+            }
+            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) {
+            return { content: [{ type: "text", text: "Database schema analysis failed." }] };
+        }
+    },
+};

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

@@ -0,0 +1,157 @@
+import fs from "fs";
+import path from "path";
+import { 
+    getFrameworkDir, 
+    collectMarkdownArtifacts, 
+    FRAMEWORK_VERSION 
+} from "../utils.js";
+
+export const frameworkTools = [
+    {
+        name: "get_framework_status",
+        description: "Get the current status of the AI Agent Framework, including active phase and agent states.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "get_project_gaps",
+        description: "Scans the project structure against the defined standards in ENDERUN.md and identifies missing files, folders, or documentation.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "codebase_status",
+        description: "Compatibility alias for get_framework_status.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "get_memory_insights",
+        description: "Analyze PROJECT_MEMORY.md and BRAIN_DASHBOARD.md to provide insights on what was done, what is being done, and the history.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "codebase_context",
+        description: "Compatibility helper for non-code context discovery. Lists known markdown artifacts under docs/ and memory files.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "get_system_time",
+        description: "Get the current system time in ISO-8601 format (UTC). Use this instead of Shell 'date' commands.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "bootstrap_legacy_memory",
+        description: "Analyzes a pre-existing codebase to automatically generate the initial project memory, learning its tech stack and architecture.",
+        inputSchema: { type: "object", properties: {} },
+    },
+];
+
+export const frameworkHandlers = {
+    bootstrap_legacy_memory: async (args: any, projectRoot: string) => {
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const memoryPath = path.join(projectRoot, frameworkDir, "PROJECT_MEMORY.md");
+            const pkgPath = path.join(projectRoot, "package.json");
+            let techStack = "Unknown";
+            if (fs.existsSync(pkgPath)) {
+                const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+                const allDeps = Object.keys(pkg.dependencies || {}).concat(Object.keys(pkg.devDependencies || {}));
+                const detected = [];
+                if (allDeps.includes("react")) detected.push("React");
+                if (allDeps.includes("next")) detected.push("Next.js");
+                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." }] };
+        }
+    },
+    get_framework_status: async (args: any, projectRoot: string) => {
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const memoryPath = path.join(projectRoot, frameworkDir, "PROJECT_MEMORY.md");
+            const memoryContent = fs.readFileSync(memoryPath, "utf-8");
+            const statusRowMatch = memoryContent.match(/\| Active Phase \| Profile \| Last Update \| Active Trace ID \| Blockers \|\n\| :----------- \| :------ \| :---------- \| :-------------- \| :------- \|\n\| ([^|]+) \| ([^|]+) \| ([^|]+) \| ([^|]+) \| ([^|]+) \|/);
+            const phase = statusRowMatch?.[1]?.trim() ?? "UNKNOWN";
+            const profile = statusRowMatch?.[2]?.trim() ?? "UNKNOWN";
+            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." }] };
+        }
+    },
+    get_project_gaps: async (args: any, projectRoot: string) => {
+        const missing: string[] = [];
+        const frameworkDir = getFrameworkDir(projectRoot);
+        const checkPaths = [
+            { path: "apps", type: "folder", optional: true },
+            { path: "packages/shared-types/src", type: "folder" },
+            { path: path.join(frameworkDir, "docs/api"), type: "folder", optional: true },
+            { path: ".env", type: "file", optional: true },
+            { path: ".env.example", type: "file" },
+            { path: path.join(frameworkDir, "PROJECT_MEMORY.md"), type: "file" },
+            { path: path.join(frameworkDir, "BRAIN_DASHBOARD.md"), type: "file" },
+            { path: "docs/tech-stack.md", type: "file" },
+            { path: "docs/project-docs.md", type: "file" },
+        ];
+        for (const item of checkPaths) {
+            const fullPath = path.join(projectRoot, item.path);
+            if (!fs.existsSync(fullPath) && !item.optional) {
+                missing.push(`[MISSING ${item.type.toUpperCase()}] ${item.path}`);
+            }
+        }
+        const agentsDir = path.join(projectRoot, frameworkDir, "agents");
+        if (!fs.existsSync(agentsDir)) {
+            missing.push(`[MISSING FOLDER] ${frameworkDir}/agents`);
+        } else {
+            const agents = fs.readdirSync(agentsDir).filter((f) => f.endsWith(".md")).map((f) => f.replace(".md", ""));
+            const logsDir = path.join(projectRoot, frameworkDir, "logs");
+            for (const agentName of agents) {
+                const logFile = path.join(logsDir, `${agentName}.json`);
+                if (!fs.existsSync(logFile)) {
+                    missing.push(`[MISSING LOG FILE] ${frameworkDir}/logs/${agentName}.json (Expected for agent ${agentName})`);
+                }
+            }
+        }
+        return { content: [{ type: "text", text: missing.length > 0 ? `Detected Gaps:\n${missing.join("\n")}` : "No structural gaps detected based on core standards." }] };
+    },
+    get_memory_insights: async (args: any, projectRoot: string) => {
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const memoryPath = path.join(projectRoot, frameworkDir, "PROJECT_MEMORY.md");
+            const dashboardPath = path.join(projectRoot, frameworkDir, "BRAIN_DASHBOARD.md");
+            const memory = fs.existsSync(memoryPath) ? fs.readFileSync(memoryPath, "utf-8") : "Memory file missing.";
+            const dashboard = fs.existsSync(dashboardPath) ? fs.readFileSync(dashboardPath, "utf-8") : "Dashboard file missing.";
+            const history = memory.split("## HISTORY")[1] || "No history found.";
+            const activeTasks = memory.split("## ACTIVE TASKS")[1]?.split("##")[0] || "No active tasks.";
+            const dashboardAgents = dashboard.split("## 📈 Visualizations")[0] || dashboard;
+            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." }] };
+        }
+    },
+    codebase_context: async (args: any, projectRoot: string) => {
+        try {
+            const artifacts = collectMarkdownArtifacts(projectRoot);
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const memoryPath = path.join(projectRoot, frameworkDir, "PROJECT_MEMORY.md");
+            const dashboardPath = path.join(projectRoot, frameworkDir, "BRAIN_DASHBOARD.md");
+            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." }] };
+        }
+    },
+    get_system_time: async () => {
+        return { content: [{ type: "text", text: new Date().toISOString() }] };
+    },
+};

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

@@ -0,0 +1,43 @@
+import path from "path";
+import { execSync } from "child_process";
+import { GENERATE_SEMANTIC_COMMIT_MESSAGE_ARGS_SCHEMA } from "../schemas.js";
+
+export const gitTools = [
+    {
+        name: "generate_semantic_commit_message",
+        description: "Analyzes staged git changes and generates a structured semantic commit message based on project standards.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                traceId: { type: "string", description: "The active Trace ID (ULID)" },
+            },
+            required: ["traceId"],
+        },
+    },
+];
+
+export const gitHandlers = {
+    generate_semantic_commit_message: async (args: any, projectRoot: string) => {
+        const parsed = GENERATE_SEMANTIC_COMMIT_MESSAGE_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success) return { content: [{ type: "text", text: "Invalid traceId argument." }] };
+        try {
+            const diff = execSync("git diff --staged", { encoding: "utf-8", cwd: projectRoot });
+            if (!diff) return { content: [{ type: "text", text: "No staged changes found." }] };
+            const files = execSync("git diff --staged --name-only", { encoding: "utf-8", cwd: projectRoot }).split("\n").filter(Boolean);
+            let type = "feat", scope = "code";
+            if (files.some(f => f.includes(".md"))) type = "docs";
+            else if (files.some(f => f.includes("shared-types"))) type = "arch";
+            else if (files.some(f => f.includes("framework-mcp"))) type = "chore";
+            else if (files.some(f => f.includes("bin/cli.js"))) type = "fix";
+            else if (files.some(f => f.includes("test"))) type = "test";
+            if (files.some(f => f.includes("apps/web"))) scope = "web";
+            else if (files.some(f => f.includes("apps/backend"))) scope = "backend";
+            else if (files.some(f => f.includes("packages/shared-types"))) scope = "contract";
+            else if (files.some(f => f.includes("packages/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." }] };
+        }
+    },
+};

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

@@ -0,0 +1,45 @@
+import { codebaseTools, codebaseHandlers } from "./codebase.js";
+import { frameworkTools, frameworkHandlers } from "./framework.js";
+import { securityTools, securityHandlers } from "./security.js";
+import { memoryTools, memoryHandlers } from "./memory.js";
+import { contractTools, contractHandlers } from "./contract.js";
+import { academyTools, academyHandlers } from "./academy.js";
+import { messageTools, messageHandlers } from "./messages.js";
+import { gitTools, gitHandlers } from "./git.js";
+import { databaseTools, databaseHandlers } from "./database.js";
+import { knowledgeTools, knowledgeHandlers } from "./knowledge.js";
+import { repositoryTools, repositoryHandlers } from "./repository.js";
+
+export const allTools = [
+    ...codebaseTools,
+    ...frameworkTools,
+    ...securityTools,
+    ...memoryTools,
+    ...contractTools,
+    ...academyTools,
+    ...messageTools,
+    ...gitTools,
+    ...databaseTools,
+    ...knowledgeTools,
+    ...repositoryTools,
+];
+
+export const allHandlers: Record<string, (args: any, projectRoot: string) => Promise<any>> = {
+    ...codebaseHandlers,
+    ...frameworkHandlers,
+    ...securityHandlers,
+    ...memoryHandlers,
+    ...contractHandlers,
+    ...academyHandlers,
+    ...messageHandlers,
+    ...gitHandlers,
+    ...databaseHandlers,
+    ...knowledgeHandlers,
+    ...repositoryHandlers,
+};
+
+// Add compatibility aliases
+allHandlers.codebase_search = allHandlers.search_codebase;
+allHandlers.codebase_graph_query = allHandlers.analyze_dependencies;
+allHandlers.codebase_status = allHandlers.get_framework_status;
+allHandlers.codebase_context_search = allHandlers.search_codebase; // Modified in original but search_codebase handles extension

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

@@ -0,0 +1,68 @@
+import fs from "fs";
+import path from "path";
+import { getFrameworkDir } from "../utils.js";
+import { 
+    SEARCH_KNOWLEDGE_BASE_ARGS_SCHEMA, 
+    UPDATE_KNOWLEDGE_BASE_ARGS_SCHEMA 
+} from "../schemas.js";
+
+export const knowledgeTools = [
+    {
+        name: "search_knowledge_base",
+        description: "Searches the Academy's internal knowledge base for architectural patterns, troubleshooting guides, and FAQs.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search query or topic" },
+            },
+            required: ["query"],
+        },
+    },
+    {
+        name: "update_knowledge_base",
+        description: "Adds or updates an entry in the Academy's internal knowledge base.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                topic: { type: "string", description: "The topic or title of the entry" },
+                content: { type: "string", description: "The technical content or guide" },
+            },
+            required: ["topic", "content"],
+        },
+    },
+];
+
+export const knowledgeHandlers = {
+    search_knowledge_base: async (args: any, projectRoot: string) => {
+        const parsed = SEARCH_KNOWLEDGE_BASE_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success) return { content: [{ type: "text", text: "Invalid search query." }] };
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const kbDir = path.join(projectRoot, frameworkDir, "knowledge");
+            if (!fs.existsSync(kbDir)) return { content: [{ type: "text", text: "Knowledge base is empty." }] };
+            const results = fs.readdirSync(kbDir).filter(f => f.endsWith(".md")).map(file => {
+                const content = fs.readFileSync(path.join(kbDir, file), "utf-8");
+                if (content.toLowerCase().includes(parsed.data.query.toLowerCase()) || file.toLowerCase().includes(parsed.data.query.toLowerCase())) {
+                    return `### ${file.replace(".md", "")}\n\n${content.slice(0, 300)}...`;
+                }
+                return null;
+            }).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 base entries found." }] };
+        } catch (error) {
+            return { content: [{ type: "text", text: "Knowledge base search failed." }] };
+        }
+    },
+    update_knowledge_base: async (args: any, projectRoot: string) => {
+        const parsed = UPDATE_KNOWLEDGE_BASE_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success) return { content: [{ type: "text", text: "Invalid topic or content." }] };
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const kbDir = path.join(projectRoot, frameworkDir, "knowledge");
+            if (!fs.existsSync(kbDir)) fs.mkdirSync(kbDir, { recursive: true });
+            fs.writeFileSync(path.join(kbDir, parsed.data.topic.replace(/[^a-z0-9]/gi, "_").toLowerCase() + ".md"), parsed.data.content);
+            return { content: [{ type: "text", text: `Knowledge base updated: ${parsed.data.topic}` }] };
+        } catch (error) {
+            return { content: [{ type: "text", text: "Failed to update knowledge base." }] };
+        }
+    },
+};

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

@@ -0,0 +1,88 @@
+import fs from "fs";
+import path from "path";
+import { 
+    getFrameworkDir, 
+    prependToSection, 
+    replaceSectionContent 
+} from "../utils.js";
+import { UPDATE_MEMORY_ARGS_SCHEMA } from "../schemas.js";
+
+export const memoryTools = [
+    {
+        name: "update_project_memory",
+        description: "Update a specific section of PROJECT_MEMORY.md (CURRENT STATUS, HISTORY, or ACTIVE TASKS) with new content.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                section: {
+                    type: "string",
+                    enum: ["CURRENT STATUS", "HISTORY", "ACTIVE TASKS"],
+                    description: "The section to update.",
+                },
+                content: {
+                    type: "string",
+                    description: "The new content to append or replace in that section.",
+                },
+            },
+            required: ["section", "content"],
+        },
+    },
+    {
+        name: "read_project_memory",
+        description: "Read the entire content of PROJECT_MEMORY.md safely. Use this instead of direct ReadFile tools to ensure framework compatibility.",
+        inputSchema: { type: "object", properties: {} },
+    },
+];
+
+export const memoryHandlers = {
+    update_project_memory: async (args: any, projectRoot: string) => {
+        const parsed = UPDATE_MEMORY_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success) return { content: [{ type: "text", text: "Invalid section or content." }] };
+        const { section, content } = parsed.data;
+        const frameworkDir = getFrameworkDir(projectRoot);
+        const memoryPath = path.join(projectRoot, frameworkDir, "PROJECT_MEMORY.md");
+        const lockPath = memoryPath + ".lock";
+        const lockOwner = `lock-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+        try {
+            if (fs.existsSync(lockPath)) {
+                const stats = fs.statSync(lockPath);
+                if (Date.now() - stats.mtimeMs > 120000) fs.unlinkSync(lockPath);
+                else return { content: [{ type: "text", text: "Memory is locked. Try again later." }] };
+            }
+            fs.writeFileSync(lockPath, JSON.stringify({ owner: lockOwner, createdAt: new Date().toISOString() }));
+            let memoryContent = fs.readFileSync(memoryPath, "utf-8");
+            if (section === "HISTORY") {
+                let updated = false;
+                const headers = ["HISTORY (Persistent Memory)", "HISTORY"];
+                for (const h of headers) {
+                    try {
+                        memoryContent = prependToSection(memoryContent, h, content);
+                        updated = true;
+                        break;
+                    } catch (e) {}
+                }
+                if (!updated) throw new Error("HISTORY section not found.");
+            } else if (section === "CURRENT STATUS") {
+                memoryContent = replaceSectionContent(memoryContent, "CURRENT STATUS", content);
+            } else if (section === "ACTIVE TASKS") {
+                memoryContent = replaceSectionContent(memoryContent, "ACTIVE TASKS", content);
+            }
+            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"}` }] };
+        }
+    },
+    read_project_memory: async (args: any, projectRoot: string) => {
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            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" }] };
+        }
+    },
+};

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

@@ -0,0 +1,70 @@
+import fs from "fs";
+import path from "path";
+import { getFrameworkDir } from "../utils.js";
+import { 
+    SEND_AGENT_MESSAGE_ARGS_SCHEMA, 
+    READ_AGENT_MESSAGES_ARGS_SCHEMA 
+} from "../schemas.js";
+
+export const messageTools = [
+    {
+        name: "send_agent_message",
+        description: "Sends a message to another specialized agent. Useful for collaboration and delegation.",
+        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" },
+            },
+            required: ["to", "message", "traceId"],
+        },
+    },
+    {
+        name: "read_agent_messages",
+        description: "Reads messages sent to the current agent.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent: { type: "string", description: "Current agent name reading their messages" },
+            },
+            required: ["agent"],
+        },
+    },
+];
+
+export const messageHandlers = {
+    send_agent_message: async (args: any, projectRoot: string) => {
+        const parsed = SEND_AGENT_MESSAGE_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success) return { content: [{ type: "text", text: "Invalid message arguments." }] };
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const recipient = parsed.data.to.replace(/^@/, "");
+            const messagesDir = path.join(projectRoot, frameworkDir, "messages");
+            if (!fs.existsSync(messagesDir)) fs.mkdirSync(messagesDir, { recursive: true });
+            const messagePath = path.join(messagesDir, `${recipient}.json`);
+            let messages = fs.existsSync(messagePath) ? JSON.parse(fs.readFileSync(messagePath, "utf-8")) : [];
+            messages.push({ timestamp: new Date().toISOString(), from: "manager", traceId: parsed.data.traceId, content: parsed.data.message, read: false });
+            fs.writeFileSync(messagePath, JSON.stringify(messages, null, 2));
+            return { content: [{ type: "text", text: `Message sent to @${recipient}.` }] };
+        } catch (error) {
+            return { content: [{ type: "text", text: "Failed to send message." }] };
+        }
+    },
+    read_agent_messages: async (args: any, projectRoot: string) => {
+        const parsed = READ_AGENT_MESSAGES_ARGS_SCHEMA.safeParse(args ?? {});
+        if (!parsed.success) return { content: [{ type: "text", text: "Invalid agent name." }] };
+        try {
+            const frameworkDir = getFrameworkDir(projectRoot);
+            const agentName = parsed.data.agent.replace(/^@/, "");
+            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"));
+            const unread = messages.filter((m: any) => !m.read);
+            fs.writeFileSync(messagePath, JSON.stringify(messages.map((m: any) => ({ ...m, read: true })), null, 2));
+            return { content: [{ type: "text", text: unread.length === 0 ? "No new messages." : `### INBOX: @${agentName}\n\n` + unread.map((m: any) => `- **From:** ${m.from}\n  **Message:** ${m.content}`).join("\n\n") }] };
+        } catch (error) {
+            return { content: [{ type: "text", text: "Failed to read messages." }] };
+        }
+    },
+};

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

@@ -0,0 +1,76 @@
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { Project } from "ts-morph";
+import { 
+    resolveSafePath, 
+    getFrameworkDir 
+} from "../utils.js";
+import { 
+    VALIDATE_REPOSITORY_HEALTH_ARGS_SCHEMA, 
+    ANALYZE_DOCUMENTATION_DEBT_ARGS_SCHEMA 
+} from "../schemas.js";
+
+export const repositoryTools = [
+    {
+        name: "validate_repository_health",
+        description: "Runs project health checks (lint, test, build) before critical actions like commits.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                scope: { type: "string", enum: ["full", "lint", "test", "build"], default: "full" },
+            },
+        },
+    },
+    {
+        name: "analyze_documentation_debt",
+        description: "Scans the codebase for missing documentation, including JSDoc, READMEs, and API contracts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to scan (relative to project root)", default: "." },
+            },
+        },
+    },
+];
+
+export const repositoryHandlers = {
+    validate_repository_health: async (args: any, projectRoot: string) => {
+        const parsed = VALIDATE_REPOSITORY_HEALTH_ARGS_SCHEMA.safeParse(args ?? {});
+        const scope = parsed.success ? parsed.data.scope : "full";
+        try {
+            const pkgPath = path.join(projectRoot, "package.json");
+            if (!fs.existsSync(pkgPath)) return { content: [{ type: "text", text: "package.json not found." }] };
+            const scripts = JSON.parse(fs.readFileSync(pkgPath, "utf-8")).scripts || {};
+            const runScript = (name: string) => scripts[name] ? { name, status: (execSync(`npm run ${name}`, { stdio: "pipe", cwd: projectRoot }) ? "PASSED" : "FAILED") } : { name, status: "SKIPPED" };
+            const results = [];
+            if (scope === "full" || scope === "lint") results.push(runScript("lint"));
+            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.status}`).join("\n") }] };
+        } catch (error) {
+            return { content: [{ type: "text", text: "Health validation failed." }] };
+        }
+    },
+    analyze_documentation_debt: async (args: any, projectRoot: string) => {
+        const parsed = ANALYZE_DOCUMENTATION_DEBT_ARGS_SCHEMA.safeParse(args ?? {});
+        const targetPath = parsed.success ? parsed.data.path : ".";
+        try {
+            const safeTargetPath = resolveSafePath(projectRoot, targetPath);
+            const tsProject = new Project();
+            tsProject.addSourceFilesAtPaths(path.join(safeTargetPath, "**/*.{ts,tsx}"));
+            const missingJSDoc: string[] = [];
+            for (const sourceFile of tsProject.getSourceFiles()) {
+                const relativePath = path.relative(projectRoot, sourceFile.getFilePath());
+                if (relativePath.includes("node_modules") || relativePath.includes("dist")) continue;
+                sourceFile.getExportedDeclarations().forEach((declarations, name) => {
+                    declarations.forEach(decl => { if (typeof (decl as any).getJsDocs === "function" && (decl as any).getJsDocs().length === 0) missingJSDoc.push(`${relativePath} -> ${name}`); });
+                });
+            }
+            const majorDirs = ["apps/backend", "apps/web", "packages/shared-types", "packages/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." }] };
+        }
+    },
+};