agent-enderun 1.1.2 → 1.1.4

package/framework-mcp/dist/tools/definitions.js

@@ -1,11 +1,13 @@
 export const TOOLS = [
     {
         name: "read_file",
-        description: "Read the content of a file within the project.",
+        description: "Read the content of a file within the project. Supports optional line range reading to prevent stream overload.",
         inputSchema: {
             type: "object",
             properties: {
                 path: { type: "string", description: "Path to the file relative to project root" },
+                startLine: { type: "number", description: "Optional starting line number (1-indexed)" },
+                endLine: { type: "number", description: "Optional ending line number (inclusive)" },
             },
             required: ["path"],
         },
@@ -73,19 +75,58 @@ export const TOOLS = [
     },
     {
         name: "send_agent_message",
-        description: "Send a Hermes protocol message to another agent.",
+        description: "Send a Hermes protocol message to another agent for collaboration or sub-tasking.",
         inputSchema: {
             type: "object",
             properties: {
-                from: { type: "string", description: "Sender agent (e.g., @manager, @backend). Defaults to @mcp if omitted." },
-                to: { type: "string", description: "Target agent (e.g., @backend, @qa)" },
-                category: { type: "string", enum: ["ACTION", "DELEGATION", "INFO", "ALERT"] },
-                content: { type: "string", description: "Message content" },
-                traceId: { type: "string", description: "Active Trace ID" },
+                from: { type: "string", description: "Sender agent (e.g., @manager, @backend)." },
+                to: { type: "string", description: "Target agent (e.g., @backend, @quality)." },
+                category: { type: "string", enum: ["ACTION", "DELEGATION", "SUBTASK", "REPLY", "ALERT"], description: "Message type." },
+                content: { type: "string", description: "Task description or message content." },
+                traceId: { type: "string", description: "Active Trace ID." },
+                parentId: { type: "string", description: "Optional parent task trace ID for hierarchical tracking." },
             },
-            required: ["to", "category", "content", "traceId"],
+            required: ["from", "to", "category", "content", "traceId"],
         },
     },
+    {
+        name: "acquire_lock",
+        description: "Acquire a stateful lock on a shared resource (like PROJECT_MEMORY.md) to prevent concurrent write conflicts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                resource: { type: "string", description: "The resource name or path to lock (e.g., 'memory')." },
+                agent: { type: "string", description: "The agent requesting the lock (e.g., '@backend')." },
+                ttl: { type: "number", description: "Time-to-live in seconds before the lock auto-expires (default: 60)." }
+            },
+            required: ["resource", "agent"]
+        }
+    },
+    {
+        name: "release_lock",
+        description: "Release a previously acquired lock on a resource.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                resource: { type: "string", description: "The resource name or path." },
+                agent: { type: "string", description: "The agent releasing the lock." }
+            },
+            required: ["resource", "agent"]
+        }
+    },
+    {
+        name: "register_agent",
+        description: "Register an agent instance with the Control Plane and validate its permissions.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent: { type: "string", description: "The agent name (e.g., '@backend')." },
+                role: { type: "string", description: "The role of the agent." },
+                capability: { type: "number", description: "The capability score (1-10)." }
+            },
+            required: ["agent", "role"]
+        }
+    },
     {
         name: "log_agent_action",
         description: "Log an agent action to the framework logs.",

package/framework-mcp/dist/tools/file_system/read_file.js

@@ -2,6 +2,26 @@ import fs from "fs";
 import { safePath } from "../../utils/security.js";
 export function handleReadFile(projectRoot, args) {
     const filePath = safePath(projectRoot, args.path);
+    const startLine = args.startLine !== undefined ? Number(args.startLine) : undefined;
+    const endLine = args.endLine !== undefined ? Number(args.endLine) : undefined;
     const content = fs.readFileSync(filePath, "utf8");
+    const lines = content.split(/\r?\n/);
+    if (startLine !== undefined || endLine !== undefined) {
+        const start = startLine !== undefined ? Math.max(1, startLine) - 1 : 0;
+        const end = endLine !== undefined ? Math.min(lines.length, endLine) : lines.length;
+        const sliced = lines.slice(start, end).join("\n");
+        return { content: [{ type: "text", text: sliced }] };
+    }
+    // Default protection limit: 1000 lines
+    const DEFAULT_MAX_LINES = 1000;
+    if (lines.length > DEFAULT_MAX_LINES) {
+        const sliced = lines.slice(0, DEFAULT_MAX_LINES).join("\n");
+        return {
+            content: [{
+                    type: "text",
+                    text: `${sliced}\n\n... [TRUNCATED - File is too long (${lines.length} lines). Only the first ${DEFAULT_MAX_LINES} lines are shown. Use startLine and endLine parameters to read other parts of the file.]`
+                }]
+        };
+    }
     return { content: [{ type: "text", text: content }] };
 }

package/framework-mcp/dist/tools/file_system/write_file.js

@@ -1,9 +1,23 @@
 import fs from "fs";
 import path from "path";
-import { safePath } from "../../utils/security.js";
+import { safePath, resolveFrameworkDir } from "../../utils/security.js";
+import { Metrics } from "../../utils/metrics.js";
 export function handleWriteFile(projectRoot, args) {
     const filePath = safePath(projectRoot, args.path);
+    const content = args.content;
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, args.content);
+    fs.writeFileSync(filePath, content);
+    // AUTO-LOGGING & METRICS
+    const tokens = Metrics.estimateTokens(content);
+    Metrics.logUsage(projectRoot, "@mcp", `write_file: ${args.path}`, tokens);
+    try {
+        const frameworkDir = resolveFrameworkDir(projectRoot);
+        const memoryPath = path.join(projectRoot, frameworkDir, "memory/PROJECT_MEMORY.md");
+        if (fs.existsSync(memoryPath)) {
+            const entry = `\n### ${new Date().toISOString().split("T")[0]} — Auto-Update\n- **Action:** wrote file \`${args.path}\` (${tokens} tokens estimated).\n`;
+            fs.appendFileSync(memoryPath, entry);
+        }
+    }
+    catch { /* ignore memory logging errors */ }
     return { content: [{ type: "text", text: `✅ File written: ${args.path}` }] };
 }

package/framework-mcp/dist/tools/index.js

@@ -9,6 +9,8 @@ import { handleOrchestrateLoop } from "./framework/orchestrate.js";
 import { handleUpdateContractHash } from "./framework/update_contract_hash.js";
 import { handleSendAgentMessage } from "./messaging/send_message.js";
 import { handleLogAgentAction } from "./messaging/log_action.js";
+import { handleAcquireLock, handleReleaseLock } from "./control_plane/locking.js";
+import { handleRegisterAgent } from "./control_plane/registry.js";
 // Map of tool names to their handler functions
 export const toolHandlers = {
     read_file: handleReadFile,
@@ -21,5 +23,8 @@ export const toolHandlers = {
     send_agent_message: handleSendAgentMessage,
     log_agent_action: handleLogAgentAction,
     update_contract_hash: handleUpdateContractHash,
+    acquire_lock: handleAcquireLock,
+    release_lock: handleReleaseLock,
+    register_agent: handleRegisterAgent,
 };
 export { TOOLS };

package/framework-mcp/dist/tools/messaging/send_message.js

@@ -1,23 +1,44 @@
 import fs from "fs";
 import path from "path";
 import { resolveFrameworkDir } from "../../utils/security.js";
-export function handleSendAgentMessage(projectRoot, args) {
+export async function handleSendAgentMessage(projectRoot, args) {
     const { to, category, content, traceId } = args;
-    // `from` is optional — falls back to "@mcp" for backward compatibility
     const from = args.from || "@mcp";
     const frameworkDir = resolveFrameworkDir(projectRoot);
+    const messagesDir = path.join(projectRoot, frameworkDir, "messages");
     const agentName = to.replace("@", "");
-    const messagePath = path.join(projectRoot, frameworkDir, "messages", `${agentName}.json`);
-    const message = {
-        timestamp: new Date().toISOString(),
-        from,
-        to,
-        category,
-        traceId,
-        content,
-        status: "PENDING"
-    };
-    fs.mkdirSync(path.dirname(messagePath), { recursive: true });
-    fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
-    return { content: [{ type: "text", text: `✅ Message sent to ${to} (from: ${from})` }] };
+    const messagePath = path.join(messagesDir, `${agentName}.json`);
+    const lockPath = path.join(messagesDir, ".lock");
+    // Hermes Lock Protocol: Retry 3 times with 500ms delay
+    let retries = 3;
+    while (retries > 0 && fs.existsSync(lockPath)) {
+        const stats = fs.statSync(lockPath);
+        if (Date.now() - stats.mtimeMs > 5000) {
+            fs.unlinkSync(lockPath);
+            break;
+        }
+        retries--;
+        if (retries > 0) {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+        }
+    }
+    try {
+        fs.mkdirSync(messagesDir, { recursive: true });
+        fs.writeFileSync(lockPath, `Locked by ${from} at ${new Date().toISOString()}`);
+        const message = {
+            timestamp: new Date().toISOString(),
+            from,
+            to,
+            category,
+            traceId,
+            content,
+            status: "PENDING"
+        };
+        fs.appendFileSync(messagePath, JSON.stringify(message) + "\n");
+        return { content: [{ type: "text", text: `✅ Message sent to ${to} (from: ${from})` }] };
+    }
+    finally {
+        if (fs.existsSync(lockPath))
+            fs.unlinkSync(lockPath);
+    }
 }

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

@@ -0,0 +1,38 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "./security.js";
+export const Metrics = {
+    /**
+     * Estimates tokens based on character count (rough heuristic: 1 token ~= 4 chars).
+     */
+    estimateTokens: (text) => {
+        return Math.ceil(text.length / 4);
+    },
+    /**
+     * Logs the token usage and action to the observability metrics file.
+     */
+    logUsage: (projectRoot, agent, action, tokens) => {
+        const frameworkDir = resolveFrameworkDir(projectRoot);
+        const metricsPath = path.join(projectRoot, frameworkDir, "observability/metrics.json");
+        try {
+            const metricsDir = path.dirname(metricsPath);
+            if (!fs.existsSync(metricsDir))
+                fs.mkdirSync(metricsDir, { recursive: true });
+            let currentMetrics = [];
+            if (fs.existsSync(metricsPath)) {
+                currentMetrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            }
+            currentMetrics.push({
+                timestamp: new Date().toISOString(),
+                agent,
+                action,
+                estimatedTokens: tokens
+            });
+            // Keep only last 100 entries to save space
+            if (currentMetrics.length > 100)
+                currentMetrics.shift();
+            fs.writeFileSync(metricsPath, JSON.stringify(currentMetrics, null, 2));
+        }
+        catch { /* ignore: metrics should not block the main process */ }
+    }
+};

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

@@ -33,15 +33,19 @@ export function resolveFrameworkDir(projectRoot) {
     catch {
         // ignore — fall through to filesystem scan
     }
-    // 2. Filesystem scan — .enderun takes precedence over adapter-specific dirs
+    // 2. Filesystem scan
     const candidates = [
         ".enderun",
+        ".cursor",
         ".claude",
+        ".github",
         ".grok",
+        ".windsurf",
+        ".antigravity",
         ".agent",
-        ".gemini/antigravity",
         ".gemini/antigravity-cli",
         ".gemini",
+        ".agents",
     ];
     for (const candidate of candidates) {
         const candidatePath = path.join(projectRoot, candidate);
@@ -49,5 +53,5 @@ export function resolveFrameworkDir(projectRoot) {
             return candidate;
         }
     }
-    return ".enderun";
+    return ".gemini";
 }

package/framework-mcp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-enderun/mcp",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "Agent Enderun Model Context Protocol (MCP) Server",
   "type": "module",
   "scripts": {

package/framework-mcp/src/index.ts

@@ -14,7 +14,7 @@ import { TOOLS, toolHandlers } from "./tools/index.js";
 const server = new Server(
     {
         name: "@agent-enderun/mcp",
-        version: "1.1.2",
+        version: "1.1.4",
     },
     {
         capabilities: {

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

@@ -0,0 +1,77 @@
+import fs from "fs";
+import path from "path";
+import { ToolResult } from "../types.js";
+import { resolveFrameworkDir } from "../../utils/security.js";
+
+interface LockArgs {
+    resource: string;
+    agent: string;
+    ttl?: number;
+}
+
+/**
+ * Handles acquiring a stateful lock on a resource.
+ */
+export async function handleAcquireLock(projectRoot: string, args: LockArgs): Promise<ToolResult> {
+    const { resource, agent, ttl = 60 } = args;
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const lockDir = path.join(projectRoot, frameworkDir, "locks");
+    const lockPath = path.join(lockDir, `${resource}.lock`);
+
+    try {
+        if (!fs.existsSync(lockDir)) fs.mkdirSync(lockDir, { recursive: true });
+
+        if (fs.existsSync(lockPath)) {
+            const stat = fs.statSync(lockPath);
+            const now = new Date().getTime();
+            const age = (now - stat.mtimeMs) / 1000;
+
+            if (age < ttl) {
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `Resource '${resource}' is currently locked by another agent.` }]
+                };
+            }
+            // Lock expired, safe to override
+            fs.unlinkSync(lockPath);
+        }
+
+        fs.writeFileSync(lockPath, JSON.stringify({ agent, timestamp: new Date().toISOString() }));
+        return {
+            content: [{ type: "text", text: `✅ Lock acquired for resource '${resource}' by ${agent}.` }]
+        };
+    } catch (e) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Failed to acquire lock: ${String(e)}` }]
+        };
+    }
+}
+
+/**
+ * Handles releasing a lock.
+ */
+export async function handleReleaseLock(projectRoot: string, args: LockArgs): Promise<ToolResult> {
+    const { resource, agent } = args;
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const lockPath = path.join(projectRoot, frameworkDir, "locks", `${resource}.lock`);
+
+    try {
+        if (!fs.existsSync(lockPath)) {
+            return { content: [{ type: "text", text: `ℹ️ No lock found for resource '${resource}'.` }] };
+        }
+
+        const lockData = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (lockData.agent !== agent) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `❌ Denied: You do not own the lock for '${resource}'. Owned by ${lockData.agent}.` }]
+            };
+        }
+
+        fs.unlinkSync(lockPath);
+        return { content: [{ type: "text", text: `✅ Lock released for resource '${resource}' by ${agent}.` }] };
+    } catch (e) {
+        return { isError: true, content: [{ type: "text", text: `Failed to release lock: ${String(e)}` }] };
+    }
+}

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

@@ -0,0 +1,44 @@
+import fs from "fs";
+import path from "path";
+import { ToolResult } from "../types.js";
+import { resolveFrameworkDir } from "../../utils/security.js";
+
+interface RegisterArgs {
+    agent: string;
+    role: string;
+    capability?: number;
+}
+
+/**
+ * Handles agent registration with the Control Plane.
+ * This can be used to validate permissions and active status.
+ */
+export async function handleRegisterAgent(projectRoot: string, args: RegisterArgs): Promise<ToolResult> {
+    const { agent, role, capability = 5 } = args;
+    const frameworkDir = resolveFrameworkDir(projectRoot);
+    const registryDir = path.join(projectRoot, frameworkDir, "registry");
+    const agentFile = path.join(registryDir, `${agent.replace("@", "")}_active.json`);
+
+    try {
+        if (!fs.existsSync(registryDir)) fs.mkdirSync(registryDir, { recursive: true });
+
+        const agentData = {
+            agent,
+            role,
+            capability,
+            last_seen: new Date().toISOString(),
+            status: "ACTIVE"
+        };
+
+        fs.writeFileSync(agentFile, JSON.stringify(agentData, null, 2));
+        
+        return {
+            content: [{ type: "text", text: `🎖️ Agent ${agent} (${role}) registered successfully in the Enderun Control Plane.` }]
+        };
+    } catch (e) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Failed to register agent: ${String(e)}` }]
+        };
+    }
+}

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

@@ -77,19 +77,58 @@ export const TOOLS: ToolDefinition[] = [
     },
     {
         name: "send_agent_message",
-        description: "Send a Hermes protocol message to another agent.",
+        description: "Send a Hermes protocol message to another agent for collaboration or sub-tasking.",
         inputSchema: {
             type: "object",
             properties: {
-                from: { type: "string", description: "Sender agent (e.g., @manager, @backend). Defaults to @mcp if omitted." },
-                to: { type: "string", description: "Target agent (e.g., @backend, @qa)" },
-                category: { type: "string", enum: ["ACTION", "DELEGATION", "INFO", "ALERT"] },
-                content: { type: "string", description: "Message content" },
-                traceId: { type: "string", description: "Active Trace ID" },
+                from: { type: "string", description: "Sender agent (e.g., @manager, @backend)." },
+                to: { type: "string", description: "Target agent (e.g., @backend, @quality)." },
+                category: { type: "string", enum: ["ACTION", "DELEGATION", "SUBTASK", "REPLY", "ALERT"], description: "Message type." },
+                content: { type: "string", description: "Task description or message content." },
+                traceId: { type: "string", description: "Active Trace ID." },
+                parentId: { type: "string", description: "Optional parent task trace ID for hierarchical tracking." },
             },
-            required: ["to", "category", "content", "traceId"],
+            required: ["from", "to", "category", "content", "traceId"],
         },
     },
+    {
+        name: "acquire_lock",
+        description: "Acquire a stateful lock on a shared resource (like PROJECT_MEMORY.md) to prevent concurrent write conflicts.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                resource: { type: "string", description: "The resource name or path to lock (e.g., 'memory')." },
+                agent: { type: "string", description: "The agent requesting the lock (e.g., '@backend')." },
+                ttl: { type: "number", description: "Time-to-live in seconds before the lock auto-expires (default: 60)." }
+            },
+            required: ["resource", "agent"]
+        }
+    },
+    {
+        name: "release_lock",
+        description: "Release a previously acquired lock on a resource.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                resource: { type: "string", description: "The resource name or path." },
+                agent: { type: "string", description: "The agent releasing the lock." }
+            },
+            required: ["resource", "agent"]
+        }
+    },
+    {
+        name: "register_agent",
+        description: "Register an agent instance with the Control Plane and validate its permissions.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                agent: { type: "string", description: "The agent name (e.g., '@backend')." },
+                role: { type: "string", description: "The role of the agent." },
+                capability: { type: "number", description: "The capability score (1-10)." }
+            },
+            required: ["agent", "role"]
+        }
+    },
     {
         name: "log_agent_action",
         description: "Log an agent action to the framework logs.",

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

@@ -1,11 +1,28 @@
 import fs from "fs";
 import path from "path";
-import { safePath } from "../../utils/security.js";
+import { safePath, resolveFrameworkDir } from "../../utils/security.js";
+import { Metrics } from "../../utils/metrics.js";
 import { ToolArgs, ToolResult } from "../types.js";
 
 export function handleWriteFile(projectRoot: string, args: ToolArgs): ToolResult {
     const filePath = safePath(projectRoot, args.path as string);
+    const content = args.content as string;
+    
     fs.mkdirSync(path.dirname(filePath), { recursive: true });
-    fs.writeFileSync(filePath, args.content as string);
+    fs.writeFileSync(filePath, content);
+    
+    // AUTO-LOGGING & METRICS
+    const tokens = Metrics.estimateTokens(content);
+    Metrics.logUsage(projectRoot, "@mcp", `write_file: ${args.path}`, tokens);
+
+    try {
+        const frameworkDir = resolveFrameworkDir(projectRoot);
+        const memoryPath = path.join(projectRoot, frameworkDir, "memory/PROJECT_MEMORY.md");
+        if (fs.existsSync(memoryPath)) {
+            const entry = `\n### ${new Date().toISOString().split("T")[0]} — Auto-Update\n- **Action:** wrote file \`${args.path}\` (${tokens} tokens estimated).\n`;
+            fs.appendFileSync(memoryPath, entry);
+        }
+    } catch { /* ignore memory logging errors */ }
+
     return { content: [{ type: "text", text: `✅ File written: ${args.path}` }] };
 }

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

@@ -9,10 +9,12 @@ import { handleOrchestrateLoop } from "./framework/orchestrate.js";
 import { handleUpdateContractHash } from "./framework/update_contract_hash.js";
 import { handleSendAgentMessage } from "./messaging/send_message.js";
 import { handleLogAgentAction } from "./messaging/log_action.js";
+import { handleAcquireLock, handleReleaseLock } from "./control_plane/locking.js";
+import { handleRegisterAgent } from "./control_plane/registry.js";
 import { ToolResult, ToolArgs } from "./types.js";
 
 // Define a type for the tool handlers
-export type ToolHandler = (projectRoot: string, args: ToolArgs) => ToolResult;
+export type ToolHandler = (projectRoot: string, args: ToolArgs) => ToolResult | Promise<ToolResult>;
 
 // Map of tool names to their handler functions
 export const toolHandlers: Record<string, ToolHandler> = {
@@ -26,6 +28,9 @@ export const toolHandlers: Record<string, ToolHandler> = {
     send_agent_message: handleSendAgentMessage,
     log_agent_action: handleLogAgentAction,
     update_contract_hash: handleUpdateContractHash,
+    acquire_lock: handleAcquireLock as ToolHandler,
+    release_lock: handleReleaseLock as ToolHandler,
+    register_agent: handleRegisterAgent as ToolHandler,
 };
 
 export { TOOLS };

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

@@ -3,7 +3,7 @@ import path from "path";
 import { resolveFrameworkDir } from "../../utils/security.js";
 import { ToolArgs, ToolResult } from "../types.js";
 
-export function handleSendAgentMessage(projectRoot: string, args: ToolArgs): ToolResult {
+export async function handleSendAgentMessage(projectRoot: string, args: ToolArgs): Promise<ToolResult> {
     const { to, category, content, traceId } = args as Required<Pick<ToolArgs, "to" | "category" | "content" | "traceId">>;
     const from = (args.from as string) || "@mcp";
 
@@ -23,8 +23,7 @@ export function handleSendAgentMessage(projectRoot: string, args: ToolArgs): Too
         }
         retries--;
         if (retries > 0) {
-            const start = Date.now();
-            while (Date.now() - start < 500); // Simple busy wait for MCP environment
+            await new Promise((resolve) => setTimeout(resolve, 500));
         }
     }
 

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

@@ -0,0 +1,53 @@
+import fs from "fs";
+import path from "path";
+import { resolveFrameworkDir } from "./security.js";
+
+/**
+ * Token and Metric Tracker for Enderun Core.
+ * Estimates token usage and logs operational costs.
+ */
+
+interface MetricEntry {
+    timestamp: string;
+    agent: string;
+    action: string;
+    estimatedTokens: number;
+}
+
+export const Metrics = {
+    /**
+     * Estimates tokens based on character count (rough heuristic: 1 token ~= 4 chars).
+     */
+    estimateTokens: (text: string): number => {
+        return Math.ceil(text.length / 4);
+    },
+
+    /**
+     * Logs the token usage and action to the observability metrics file.
+     */
+    logUsage: (projectRoot: string, agent: string, action: string, tokens: number) => {
+        const frameworkDir = resolveFrameworkDir(projectRoot);
+        const metricsPath = path.join(projectRoot, frameworkDir, "observability/metrics.json");
+        try {
+            const metricsDir = path.dirname(metricsPath);
+            if (!fs.existsSync(metricsDir)) fs.mkdirSync(metricsDir, { recursive: true });
+
+            let currentMetrics: MetricEntry[] = [];
+            if (fs.existsSync(metricsPath)) {
+                currentMetrics = JSON.parse(fs.readFileSync(metricsPath, "utf8"));
+            }
+
+            currentMetrics.push({
+                timestamp: new Date().toISOString(),
+                agent,
+                action,
+                estimatedTokens: tokens
+            });
+
+            // Keep only last 100 entries to save space
+            if (currentMetrics.length > 100) currentMetrics.shift();
+
+            fs.writeFileSync(metricsPath, JSON.stringify(currentMetrics, null, 2));
+        } catch { /* ignore: metrics should not block the main process */ }
+    }
+};

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

@@ -37,15 +37,19 @@ export function resolveFrameworkDir(projectRoot: string): string {
         // ignore — fall through to filesystem scan
     }
 
-    // 2. Filesystem scan — .enderun takes precedence over adapter-specific dirs
+    // 2. Filesystem scan
     const candidates = [
         ".enderun",
+        ".cursor",
         ".claude",
+        ".github",
         ".grok",
+        ".windsurf",
+        ".antigravity",
         ".agent",
-        ".gemini/antigravity",
         ".gemini/antigravity-cli",
         ".gemini",
+        ".agents",
     ];
 
     for (const candidate of candidates) {
@@ -55,5 +59,6 @@ export function resolveFrameworkDir(projectRoot: string): string {
         }
     }
 
-    return ".enderun";
+    return ".gemini";
 }
+