agent-enderun 0.5.1 → 0.5.2

package/bin/update-contract.js

@@ -12,13 +12,32 @@ const projectRoot = path.join(__dirname, "..");
 const contractPath = path.join(projectRoot, "packages/shared-types/contract.version.json");
 const sharedTypesDir = path.join(projectRoot, "packages/shared-types/src");
 
+function collectTypeFiles(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...collectTypeFiles(fullPath));
+    } else if (entry.name.endsWith(".ts")) {
+      files.push(fullPath);
+    }
+  }
+
+  return files;
+}
+
 function calculateHash(dir) {
   const hash = crypto.createHash("sha256");
-  const files = fs.readdirSync(dir).filter(f => f.endsWith(".ts") || f.endsWith(".json")).sort();
+  const files = collectTypeFiles(dir).sort();
   
   files.forEach(file => {
-    const content = fs.readFileSync(path.join(dir, file));
+    const content = fs.readFileSync(file);
+    hash.update(path.relative(projectRoot, file));
+    hash.update("\0");
     hash.update(content);
+    hash.update("\0");
   });
   
   return hash.digest("hex");

package/claude.md

@@ -2,7 +2,7 @@
 
 This file is the entry point for Claude. The project's "Supreme Law" and all instructions are located in the following file:
 
-👉 **[{{FRAMEWORK_DIR}}/ENDERUN.md]({{FRAMEWORK_DIR}}/ENDERUN.md)**
+👉 **[.claude/ENDERUN.md](.claude/ENDERUN.md)**
 
 ### 🤖 AGENT DIRECTIVE
 You are ALWAYS operating as `@manager` (Team-Lead) by default — on every message, every turn. The user does NOT need to type `@manager`. Typing a specific agent (e.g. `@backend`) explicitly will override this and activate that specialist role directly. You are responsible for analysis and delegation.

package/codex.md

@@ -2,7 +2,7 @@
 
 This file is the entry point for Codex. The project's "Supreme Law" and all instructions are located in the following file:
 
-👉 **[{{FRAMEWORK_DIR}}/ENDERUN.md]({{FRAMEWORK_DIR}}/ENDERUN.md)**
+👉 **[.enderun/ENDERUN.md](.enderun/ENDERUN.md)**
 
 ### 🤖 AGENT DIRECTIVE
 You are ALWAYS operating as `@manager` (Team-Lead) by default — on every message, every turn. The user does NOT need to type `@manager`. Typing a specific agent (e.g. `@backend`) explicitly will override this and activate that specialist role directly. You are responsible for analysis and delegation.

package/cursor.md

@@ -2,7 +2,7 @@
 
 This file is the entry point for Cursor. The project's "Supreme Law" and all instructions are located in the following file:
 
-👉 **[{{FRAMEWORK_DIR}}/ENDERUN.md]({{FRAMEWORK_DIR}}/ENDERUN.md)**
+👉 **[.cursor/ENDERUN.md](.cursor/ENDERUN.md)**
 
 ### 🤖 AGENT DIRECTIVE
 You are ALWAYS operating as `@manager` (Team-Lead) by default — on every message, every turn. The user does NOT need to type `@manager`. Typing a specific agent (e.g. `@backend`) explicitly will override this and activate that specialist role directly. You are responsible for analysis and delegation.

package/docs/README.md

@@ -0,0 +1,23 @@
+# Project Documentation
+
+This folder is managed by **Agent Enderun agents** and contains documentation
+generated for **your project** — not the framework itself.
+
+## What Goes Here
+
+| File | Owner Agent | Description |
+| :--- | :--- | :--- |
+| `architecture.md` | @backend | System architecture and data flow diagrams |
+| `api-reference.md` | @backend | Public API endpoints and usage examples |
+| `components.md` | @frontend | UI component catalog and usage guidelines |
+| `deployment.md` | @manager | Deployment steps and environment setup |
+| `decisions.md` | @manager | Architecture Decision Records (ADRs) |
+
+## Distinction from `.enderun/docs/`
+
+| Path | Purpose |
+| :--- | :--- |
+| `/docs/` | **Your project** documentation — written by agents as features are built |
+| `/.enderun/docs/` | **Framework** configuration — tech-stack, security policy, privacy policy |
+
+> Agents will populate this folder automatically during **PHASE_2 (Core Development)**.

package/gemini-extension.json

@@ -1,5 +1,11 @@
 {
   "name": "Agent Enderun",
   "description": "Enterprise-grade AI orchestration framework for software teams.",
-  "instructions": "{{FRAMEWORK_DIR}}/ENDERUN.md"
-}
+  "instructions": ".gemini/ENDERUN.md",
+  "mcpServers": {
+    "agent-enderun": {
+      "command": "node",
+      "args": ["packages/framework-mcp/dist/index.js"]
+    }
+  }
+}

package/gemini.md

@@ -2,7 +2,7 @@
 
 This file is the entry point for Gemini. The project's "Supreme Law" and all instructions are located in the following file:
 
-👉 **[{{FRAMEWORK_DIR}}/ENDERUN.md]({{FRAMEWORK_DIR}}/ENDERUN.md)**
+👉 **[.gemini/ENDERUN.md](.gemini/ENDERUN.md)**
 
 ### 🤖 AGENT DIRECTIVE
 You are ALWAYS operating as `@manager` (Team-Lead) by default — on every message, every turn. The user does NOT need to type `@manager`. Typing a specific agent (e.g. `@backend`) explicitly will override this and activate that specialist role directly. You are responsible for analysis and delegation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-enderun",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "The Supreme AI Governance & Orchestration Framework for Enterprise Development",
   "author": "Yusuf BEKAR",
   "license": "MIT",
@@ -51,7 +51,8 @@
     "gemini-extension.json",
     "cursor.md",
     "claude.md",
-    "codex.md"
+    "codex.md",
+    "docs"
   ],
   "scripts": {
     "enderun:build": "npm run build --workspaces --if-present",
@@ -78,7 +79,7 @@
     "vitest": "^3.0.5"
   },
   "enderun": {
-    "version": "0.5.1",
+    "version": "0.5.2",
     "initializedAt": "2026-05-09T13:24:27.472Z"
   }
 }

package/packages/framework-mcp/dist/schemas.js

@@ -38,6 +38,7 @@ export const SEARCH_KNOWLEDGE_BASE_ARGS_SCHEMA = z.object({
 export const UPDATE_KNOWLEDGE_BASE_ARGS_SCHEMA = z.object({
     topic: z.string().min(1),
     content: z.string().min(1),
+    tags: z.array(z.string().min(1)).default([]),
 });
 export const ANALYZE_DATABASE_SCHEMA_ARGS_SCHEMA = z.object({
     path: z.string().default("apps/backend"),
@@ -63,6 +64,7 @@ export const VALIDATE_REPOSITORY_HEALTH_ARGS_SCHEMA = z.object({
 });
 export const READ_AGENT_MESSAGES_ARGS_SCHEMA = z.object({
     agent: z.string().min(1),
+    traceId: z.string().min(1).optional(),
 });
 export const VERIFY_CONTRACT_INTEGRITY_ARGS_SCHEMA = z.object({
     domain: z.string().min(1),

package/packages/framework-mcp/dist/tools/contract.js

@@ -4,6 +4,17 @@ import crypto from "crypto";
 import { Project } from "ts-morph";
 import { getFrameworkDir, collectFilesRecursively } from "../utils.js";
 import { VERIFY_CONTRACT_INTEGRITY_ARGS_SCHEMA } from "../schemas.js";
+function calculateContractHash(sharedTypesDir, projectRoot) {
+    const files = collectFilesRecursively(sharedTypesDir, new Set(["ts"])).sort();
+    const hash = crypto.createHash("sha256");
+    files.forEach((filePath) => {
+        hash.update(path.relative(projectRoot, filePath));
+        hash.update("\0");
+        hash.update(fs.readFileSync(filePath));
+        hash.update("\0");
+    });
+    return hash.digest("hex");
+}
 export const contractTools = [
     {
         name: "verify_api_contract",
@@ -37,10 +48,7 @@ export const contractHandlers = {
             const contractJsonPath = path.join(projectRoot, "packages/shared-types/contract.version.json");
             if (!fs.existsSync(sharedTypesDir) || !fs.existsSync(contractJsonPath))
                 return { content: [{ type: "text", text: "Missing shared-types directory or contract.version.json" }] };
-            const files = collectFilesRecursively(sharedTypesDir, new Set(["ts"])).sort();
-            const hash = crypto.createHash("sha256");
-            files.forEach(f => hash.update(fs.readFileSync(f)));
-            const currentHash = hash.digest("hex");
+            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)}...).` }] };
         }
@@ -57,9 +65,7 @@ export const contractHandlers = {
             const files = collectFilesRecursively(sharedTypesDir, new Set(["ts"])).sort();
             if (files.length === 0)
                 return { content: [{ type: "text", text: "⚠️ WARNING: No TypeScript files found in shared-types/src. Hash not updated." }] };
-            const hash = crypto.createHash("sha256");
-            files.forEach(f => hash.update(fs.readFileSync(f)));
-            const currentHash = hash.digest("hex");
+            const currentHash = calculateContractHash(sharedTypesDir, projectRoot);
             const contractJson = fs.existsSync(contractJsonPath) ? JSON.parse(fs.readFileSync(contractJsonPath, "utf-8")) : {};
             contractJson.contract_hash = currentHash;
             contractJson.last_updated = new Date().toISOString();

package/packages/framework-mcp/dist/tools/knowledge.js

@@ -90,7 +90,7 @@ export const knowledgeHandlers = {
             if (!fs.existsSync(kbDir))
                 fs.mkdirSync(kbDir, { recursive: true });
             const fileName = parsed.data.topic.replace(/[^a-z0-9]/gi, "_").toLowerCase() + ".md";
-            const tags = parsed.data.tags || [];
+            const tags = parsed.data.tags;
             let finalContent = parsed.data.content;
             if (!finalContent.startsWith("---")) {
                 const frontmatter = `---\ntitle: ${parsed.data.topic}\ntags: [${tags.join(", ")}]\nlast_updated: ${new Date().toISOString()}\n---\n\n`;

package/packages/framework-mcp/dist/tools/messages.js

@@ -42,6 +42,10 @@ export const messageTools = [
         },
     },
 ];
+function normalizeAgentName(agent) {
+    const normalized = agent.replace(/^@/, "").trim();
+    return /^[a-z0-9_-]+$/i.test(normalized) ? normalized : null;
+}
 export const messageHandlers = {
     send_agent_message: async (args, projectRoot) => {
         const parsed = SEND_AGENT_MESSAGE_ARGS_SCHEMA.safeParse(args ?? {});
@@ -49,7 +53,9 @@ export const messageHandlers = {
             return { content: [{ type: "text", text: "Invalid message arguments." }] };
         try {
             const frameworkDir = getFrameworkDir(projectRoot);
-            const recipient = parsed.data.to.replace(/^@/, "");
+            const recipient = normalizeAgentName(parsed.data.to);
+            if (!recipient)
+                return { content: [{ type: "text", text: "Invalid recipient agent name." }] };
             const messagesDir = path.join(projectRoot, frameworkDir, "messages");
             if (!fs.existsSync(messagesDir))
                 fs.mkdirSync(messagesDir, { recursive: true });
@@ -77,14 +83,15 @@ export const messageHandlers = {
             return { content: [{ type: "text", text: "Invalid agent name." }] };
         try {
             const frameworkDir = getFrameworkDir(projectRoot);
-            const agentName = parsed.data.agent.replace(/^@/, "");
+            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 found." }] };
             const messages = JSON.parse(fs.readFileSync(messagePath, "utf-8"));
-            const unread = messages.filter((m) => !m.read);
-            // Mark as read
-            fs.writeFileSync(messagePath, JSON.stringify(messages.map((m) => ({ ...m, read: true })), null, 2));
+            const unread = messages.filter((m) => !m.read && (!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));
             if (unread.length === 0)
                 return { content: [{ type: "text", text: "No new messages." }] };
             const formatted = unread.map((m) => `- [${m.priority}] **${m.from}** (${m.category}): ${m.content} *(Trace: ${m.traceId})*`).join("\n");
@@ -100,7 +107,9 @@ export const messageHandlers = {
             return { content: [{ type: "text", text: "Invalid agent name." }] };
         try {
             const frameworkDir = getFrameworkDir(projectRoot);
-            const agentName = parsed.data.agent.replace(/^@/, "");
+            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: "Inbox empty." }] };

package/packages/framework-mcp/dist/tools/repository.js

@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { execSync } from "child_process";
+import { spawnSync } from "child_process";
 import { Project } from "ts-morph";
 import { resolveSafePath } from "../utils.js";
 import { VALIDATE_REPOSITORY_HEALTH_ARGS_SCHEMA, ANALYZE_DOCUMENTATION_DEBT_ARGS_SCHEMA } from "../schemas.js";
@@ -35,7 +35,28 @@ export const repositoryHandlers = {
             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) => scripts[name] ? { name, status: (execSync(`npm run ${name}`, { stdio: "pipe", cwd: projectRoot }) ? "PASSED" : "FAILED") } : { name, status: "SKIPPED" };
+            const scriptCandidates = {
+                lint: ["lint", "enderun:lint"],
+                test: ["test", "enderun:test"],
+                build: ["build", "enderun:build"],
+            };
+            const runScript = (name) => {
+                const scriptName = scriptCandidates[name].find((candidate) => scripts[candidate]);
+                if (!scriptName)
+                    return { name, script: "-", status: "SKIPPED", details: "No matching script found." };
+                const result = spawnSync("npm", ["run", scriptName], {
+                    cwd: projectRoot,
+                    encoding: "utf-8",
+                    stdio: "pipe",
+                });
+                const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+                return {
+                    name,
+                    script: scriptName,
+                    status: result.status === 0 ? "PASSED" : "FAILED",
+                    details: output.split("\n").slice(-5).join("\n"),
+                };
+            };
             const results = [];
             if (scope === "full" || scope === "lint")
                 results.push(runScript("lint"));
@@ -43,7 +64,7 @@ export const repositoryHandlers = {
                 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") }] };
+            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." }] };

package/packages/framework-mcp/dist/utils.js

@@ -1,8 +1,8 @@
 import path from "path";
 import fs from "fs";
-export const FRAMEWORK_VERSION = "0.5.1";
+export const FRAMEWORK_VERSION = "0.5.2";
 export function getFrameworkDir(projectRoot) {
-    const adapters = [".gemini", ".claude", ".cursor", ".codex", ".enderun"];
+    const adapters = [".gemini", ".claude", ".cursor", ".enderun", ".codex"];
     for (const adp of adapters) {
         const fullPath = path.join(projectRoot, adp);
         if (fs.existsSync(fullPath) && fs.lstatSync(fullPath).isDirectory()) {

package/packages/framework-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-enderun-mcp",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Enterprise-grade MCP Server for AI Agent Framework",
   "author": "Yusuf BEKAR",
   "license": "MIT",
@@ -26,7 +26,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "npx tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },

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

@@ -46,6 +46,7 @@ export const SEARCH_KNOWLEDGE_BASE_ARGS_SCHEMA = z.object({
 export const UPDATE_KNOWLEDGE_BASE_ARGS_SCHEMA = z.object({
     topic: z.string().min(1),
     content: z.string().min(1),
+    tags: z.array(z.string().min(1)).default([]),
 });
 
 export const ANALYZE_DATABASE_SCHEMA_ARGS_SCHEMA = z.object({
@@ -79,6 +80,7 @@ export const VALIDATE_REPOSITORY_HEALTH_ARGS_SCHEMA = z.object({
 
 export const READ_AGENT_MESSAGES_ARGS_SCHEMA = z.object({
     agent: z.string().min(1),
+    traceId: z.string().min(1).optional(),
 });
 
 export const VERIFY_CONTRACT_INTEGRITY_ARGS_SCHEMA = z.object({

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

@@ -8,6 +8,18 @@ import {
 } from "../utils.js";
 import { VERIFY_CONTRACT_INTEGRITY_ARGS_SCHEMA } from "../schemas.js";
 
+function calculateContractHash(sharedTypesDir: string, projectRoot: string): string {
+    const files = collectFilesRecursively(sharedTypesDir, new Set(["ts"])).sort();
+    const hash = crypto.createHash("sha256");
+    files.forEach((filePath) => {
+        hash.update(path.relative(projectRoot, filePath));
+        hash.update("\0");
+        hash.update(fs.readFileSync(filePath));
+        hash.update("\0");
+    });
+    return hash.digest("hex");
+}
+
 export const contractTools = [
     {
         name: "verify_api_contract",
@@ -41,10 +53,7 @@ export const contractHandlers = {
             const sharedTypesDir = path.join(projectRoot, "packages/shared-types/src");
             const contractJsonPath = path.join(projectRoot, "packages/shared-types/contract.version.json");
             if (!fs.existsSync(sharedTypesDir) || !fs.existsSync(contractJsonPath)) return { content: [{ type: "text", text: "Missing shared-types directory or contract.version.json" }] };
-            const files = collectFilesRecursively(sharedTypesDir, new Set(["ts"])).sort();
-            const hash = crypto.createHash("sha256");
-            files.forEach(f => hash.update(fs.readFileSync(f)));
-            const currentHash = hash.digest("hex");
+            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) {
@@ -58,9 +67,7 @@ export const contractHandlers = {
             if (!fs.existsSync(sharedTypesDir)) return { content: [{ type: "text", text: "Missing shared-types directory" }] };
             const files = collectFilesRecursively(sharedTypesDir, new Set(["ts"])).sort();
             if (files.length === 0) return { content: [{ type: "text", text: "⚠️ WARNING: No TypeScript files found in shared-types/src. Hash not updated." }] };
-            const hash = crypto.createHash("sha256");
-            files.forEach(f => hash.update(fs.readFileSync(f)));
-            const currentHash = hash.digest("hex");
+            const currentHash = calculateContractHash(sharedTypesDir, projectRoot);
             const contractJson = fs.existsSync(contractJsonPath) ? JSON.parse(fs.readFileSync(contractJsonPath, "utf-8")) : {};
             contractJson.contract_hash = currentHash;
             contractJson.last_updated = new Date().toISOString();

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

@@ -95,7 +95,7 @@ export const knowledgeHandlers = {
             if (!fs.existsSync(kbDir)) fs.mkdirSync(kbDir, { recursive: true });
             
             const fileName = parsed.data.topic.replace(/[^a-z0-9]/gi, "_").toLowerCase() + ".md";
-            const tags = (parsed as any).data.tags || [];
+            const tags = parsed.data.tags;
             
             let finalContent = parsed.data.content;
             if (!finalContent.startsWith("---")) {

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

@@ -58,13 +58,19 @@ interface Message {
     read: boolean;
 }
 
+function normalizeAgentName(agent: string): string | null {
+    const normalized = agent.replace(/^@/, "").trim();
+    return /^[a-z0-9_-]+$/i.test(normalized) ? normalized : null;
+}
+
 export const messageHandlers = {
     send_agent_message: async (args: unknown, 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 recipient = normalizeAgentName(parsed.data.to);
+            if (!recipient) return { content: [{ type: "text", text: "Invalid recipient agent name." }] };
             const messagesDir = path.join(projectRoot, frameworkDir, "messages");
             if (!fs.existsSync(messagesDir)) fs.mkdirSync(messagesDir, { recursive: true });
             const messagePath = path.join(messagesDir, `${recipient}.json`);
@@ -73,8 +79,8 @@ export const messageHandlers = {
                 timestamp: new Date().toISOString(), 
                 from: "manager", 
                 traceId: parsed.data.traceId, 
-                category: parsed.data.category as any,
-                priority: parsed.data.priority as any,
+                category: parsed.data.category,
+                priority: parsed.data.priority,
                 content: parsed.data.message, 
                 read: false 
             });
@@ -89,14 +95,16 @@ export const messageHandlers = {
         if (!parsed.success) return { content: [{ type: "text", text: "Invalid agent name." }] };
         try {
             const frameworkDir = getFrameworkDir(projectRoot);
-            const agentName = parsed.data.agent.replace(/^@/, "");
+            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 found." }] };
             const messages = JSON.parse(fs.readFileSync(messagePath, "utf-8")) as Message[];
-            const unread = messages.filter((m) => !m.read);
+            const unread = messages.filter((m) => !m.read && (!parsed.data.traceId || m.traceId === parsed.data.traceId));
             
-            // Mark as read
-            fs.writeFileSync(messagePath, JSON.stringify(messages.map((m) => ({ ...m, read: true })), null, 2));
+            fs.writeFileSync(messagePath, JSON.stringify(messages.map((m) => (
+                !m.read && (!parsed.data.traceId || m.traceId === parsed.data.traceId) ? { ...m, read: true } : m
+            )), null, 2));
             
             if (unread.length === 0) return { content: [{ type: "text", text: "No new messages." }] };
             
@@ -114,7 +122,8 @@ export const messageHandlers = {
         if (!parsed.success) return { content: [{ type: "text", text: "Invalid agent name." }] };
         try {
             const frameworkDir = getFrameworkDir(projectRoot);
-            const agentName = parsed.data.agent.replace(/^@/, "");
+            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: "Inbox empty." }] };
             const messages = JSON.parse(fs.readFileSync(messagePath, "utf-8")) as Message[];

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

@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { execSync } from "child_process";
+import { spawnSync } from "child_process";
 import { Project } from "ts-morph";
 import { 
     resolveSafePath, 
@@ -42,12 +42,33 @@ export const repositoryHandlers = {
             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 scriptCandidates: Record<string, string[]> = {
+                lint: ["lint", "enderun:lint"],
+                test: ["test", "enderun:test"],
+                build: ["build", "enderun:build"],
+            };
+            const runScript = (name: string) => {
+                const scriptName = scriptCandidates[name].find((candidate) => scripts[candidate]);
+                if (!scriptName) return { name, script: "-", status: "SKIPPED", details: "No matching script found." };
+
+                const result = spawnSync("npm", ["run", scriptName], {
+                    cwd: projectRoot,
+                    encoding: "utf-8",
+                    stdio: "pipe",
+                });
+                const output = `${result.stdout || ""}${result.stderr || ""}`.trim();
+                return {
+                    name,
+                    script: scriptName,
+                    status: result.status === 0 ? "PASSED" : "FAILED",
+                    details: output.split("\n").slice(-5).join("\n"),
+                };
+            };
             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") }] };
+            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." }] };
         }

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

@@ -1,10 +1,10 @@
 import path from "path";
 import fs from "fs";
 
-export const FRAMEWORK_VERSION = "0.5.1";
+export const FRAMEWORK_VERSION = "0.5.2";
 
 export function getFrameworkDir(projectRoot: string): string {
-    const adapters = [".gemini", ".claude", ".cursor", ".codex", ".enderun"];
+    const adapters = [".gemini", ".claude", ".cursor", ".enderun", ".codex"];
     for (const adp of adapters) {
         const fullPath = path.join(projectRoot, adp);
         if (fs.existsSync(fullPath) && fs.lstatSync(fullPath).isDirectory()) {

package/packages/shared-types/contract.version.json

@@ -1,7 +1,7 @@
 {
   "version": "0.1.11",
-  "last_updated": "2026-05-15T21:03:22.437Z",
-  "contract_hash": "e9dff509023440c66449ca811b8cbbe3e159ca95c8a328976f01771dee62b7af",
+  "last_updated": "2026-05-16T16:47:16.000Z",
+  "contract_hash": "8574144a23e68351f48365f5ccb3d69dc11629af54ec9c1ed0fffd57f967b777",
   "breaking_changes": [
     {
       "version": "0.1.11",
@@ -9,4 +9,4 @@
     }
   ],
   "deprecated_versions": []
-}
+}

package/packages/shared-types/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-enderun/shared-types",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Shared TypeScript types for AI-Enderun Framework. Ensures Contract-First synchronization between agents.",
   "author": "Yusuf BEKAR",
   "license": "MIT",
@@ -23,9 +23,9 @@
     "README.md"
   ],
   "scripts": {
-    "build": "npx tsc -p tsconfig.json",
-    "build:watch": "npx tsc -p tsconfig.json --watch",
-    "typecheck": "npx tsc -p tsconfig.json --noEmit"
+    "build": "tsc -p tsconfig.json",
+    "build:watch": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "license": "MIT",
   "devDependencies": {

package/panda.config.ts

@@ -5,7 +5,11 @@ export default defineConfig({
   preflight: true,
   
   // Where to look for your css declarations
-  include: ["./src/**/*.{js,jsx,ts,tsx}", "./pages/**/*.{js,jsx,ts,tsx}"],
+  include: [
+    "./src/**/*.{js,jsx,ts,tsx}",
+    "./pages/**/*.{js,jsx,ts,tsx}",
+    "./apps/**/*.{js,jsx,ts,tsx}",
+  ],
 
   // Files to exclude
   exclude: [],

package/packages/framework-mcp/dist/index.d.ts

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

package/packages/shared-types/dist/index.d.ts.map

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