fraim-framework 2.0.87 → 2.0.89

package/dist/src/local-mcp-server/stdio-server.js

@@ -28,6 +28,7 @@ const axios_1 = __importDefault(require("axios"));
 const provider_utils_1 = require("../core/utils/provider-utils");
 const object_utils_1 = require("../core/utils/object-utils");
 const local_registry_resolver_1 = require("../core/utils/local-registry-resolver");
+const ai_mentor_1 = require("../core/ai-mentor");
 /**
  * Handle template substitution logic separately for better testability
  */
@@ -60,11 +61,33 @@ class FraimTemplateEngine {
     setRepoInfo(repoInfo) {
         this.repoInfo = repoInfo;
     }
+    setAgentInfo(info) {
+        this.agentInfo = info;
+    }
+    setMachineInfo(info) {
+        this.machineInfo = info;
+    }
     setConfig(config) {
         this.config = config;
     }
     substituteTemplates(content) {
         let result = content;
+        // 0. Substitute runtime context tokens: {{agent.*}}, {{machine.*}}, {{repository.*}}
+        //    These come from the fraim_connect payload captured during handshake.
+        const contexts = {
+            agent: this.agentInfo,
+            machine: this.machineInfo,
+            repository: this.repoInfo
+        };
+        result = result.replace(/\{\{(agent|machine|repository)\.([^}]+)\}\}/g, (match, ns, path) => {
+            const source = contexts[ns];
+            if (source) {
+                const value = (0, object_utils_1.getNestedValue)(source, path.trim());
+                if (value !== undefined)
+                    return String(value);
+            }
+            return match;
+        });
         // First, substitute config variables with fallback support.
         // Fallbacks must work even when local config is unavailable.
         result = result.replace(/\{\{proxy\.config\.([^}|]+)(?:\s*\|\s*"([^"]+)")?\}\}/g, (match, path, fallback) => {
@@ -210,11 +233,12 @@ FraimTemplateEngine.ISSUE_ACTIONS = new Set([
     'list_issues'
 ]);
 class FraimLocalMCPServer {
-    constructor() {
+    constructor(writer) {
         this.config = null;
         this.clientSupportsRoots = false;
         this.workspaceRoot = null;
         this.pendingRootsRequest = false;
+        this.agentInfo = null;
         this.machineInfo = null;
         this.repoInfo = null;
         this.engine = null;
@@ -226,6 +250,7 @@ class FraimLocalMCPServer {
         this.pendingFallbackTokenCounts = new Map();
         this.pendingFallbackEvents = [];
         this.fallbackSummaryEmitted = false;
+        this.writer = writer || process.stdout.write.bind(process.stdout);
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = this.loadApiKey();
         this.localVersion = this.detectLocalVersion();
@@ -311,21 +336,6 @@ class FraimLocalMCPServer {
             this.log(`✅ Using workspace root from MCP roots: ${this.workspaceRoot}`);
             return this.workspaceRoot;
         }
-        // Log all potentially useful environment variables for debugging
-        this.log(`🔍 Environment variables:`);
-        this.log(`   WORKSPACE_FOLDER_PATHS: ${process.env.WORKSPACE_FOLDER_PATHS || '(not set)'}`);
-        this.log(`   WORKSPACE_FOLDER: ${process.env.WORKSPACE_FOLDER || '(not set)'}`);
-        this.log(`   PROJECT_ROOT: ${process.env.PROJECT_ROOT || '(not set)'}`);
-        this.log(`   VSCODE_CWD: ${process.env.VSCODE_CWD || '(not set)'}`);
-        this.log(`   INIT_CWD: ${process.env.INIT_CWD || '(not set)'}`);
-        this.log(`   HOME: ${process.env.HOME || '(not set)'}`);
-        this.log(`   USERPROFILE: ${process.env.USERPROFILE || '(not set)'}`);
-        this.log(`   PWD: ${process.env.PWD || '(not set)'}`);
-        this.log(`   OLDPWD: ${process.env.OLDPWD || '(not set)'}`);
-        // Log ALL env vars that might contain workspace info
-        Object.keys(process.env).filter(k => k.toLowerCase().includes('workspace') || k.toLowerCase().includes('project') || k.toLowerCase().includes('kiro')).forEach(k => {
-            this.log(`   ${k}: ${process.env[k]}`);
-        });
         // Priority 1: Check for IDE-provided workspace environment variables
         const workspaceHints = [
             process.env.WORKSPACE_FOLDER_PATHS?.split(':')[0], // Cursor provides this (colon-separated for multi-root)
@@ -448,33 +458,8 @@ class FraimLocalMCPServer {
                 }).trim();
             }
             catch (error) {
-                // If git command fails, construct URL from config if available.
-                const repositoryConfig = this.config?.repository;
-                if (repositoryConfig?.url) {
-                    repoUrl = repositoryConfig.url;
-                    this.log(`Constructed repo URL from config: ${repoUrl}`);
-                }
-                else if (repositoryConfig?.provider === 'github' && repositoryConfig.owner && repositoryConfig.name) {
-                    repoUrl = `https://github.com/${repositoryConfig.owner}/${repositoryConfig.name}.git`;
-                    this.log(`Constructed repo URL from config: ${repoUrl}`);
-                }
-                else if (repositoryConfig?.provider === 'ado' &&
-                    repositoryConfig.organization &&
-                    repositoryConfig.project &&
-                    repositoryConfig.name) {
-                    repoUrl = `https://dev.azure.com/${repositoryConfig.organization}/${repositoryConfig.project}/_git/${repositoryConfig.name}`;
-                    this.log(`Constructed repo URL from config: ${repoUrl}`);
-                }
-                else if (repositoryConfig?.provider === 'gitlab') {
-                    const projectPath = repositoryConfig.projectPath
-                        || (repositoryConfig.namespace && repositoryConfig.name
-                            ? `${repositoryConfig.namespace}/${repositoryConfig.name}`
-                            : null);
-                    if (projectPath) {
-                        repoUrl = `https://gitlab.com/${projectPath}.git`;
-                        this.log(`Constructed repo URL from config: ${repoUrl}`);
-                    }
-                }
+                // Fall back to config if git fails
+                repoUrl = this.config?.repository?.url || '';
             }
             if (!repoUrl) {
                 this.log('No git repository found and no config available');
@@ -620,12 +605,21 @@ class FraimLocalMCPServer {
                 projectRoot: this.findProjectRoot(),
                 logFn: (msg) => this.log(msg)
             });
+            // Apply stored runtime context if available.
+            if (this.agentInfo)
+                this.engine.setAgentInfo(this.agentInfo);
+            if (this.machineInfo)
+                this.engine.setMachineInfo(this.machineInfo);
         }
         else {
             this.engine.setConfig(this.config);
             if (this.repoInfo) {
                 this.engine.setRepoInfo(this.repoInfo);
             }
+            if (this.agentInfo)
+                this.engine.setAgentInfo(this.agentInfo);
+            if (this.machineInfo)
+                this.engine.setMachineInfo(this.machineInfo);
         }
         return this.engine;
     }
@@ -663,11 +657,14 @@ class FraimLocalMCPServer {
             method: 'tools/call',
             params: {
                 name: 'get_fraim_file',
-                arguments: { path }
+                arguments: {
+                    path,
+                    raw: true
+                }
             }
         };
         this.applyRequestSessionId(request, requestSessionId);
-        const response = await this.proxyToRemote(request);
+        const response = await this._doProxyToRemote(request);
         if (response.error) {
             this.log(`⚠️ Failed to fetch registry file ${path}: ${response.error.message}`);
             return null;
@@ -790,13 +787,7 @@ class FraimLocalMCPServer {
         }
         return this.applyAgentFallbackForUnresolvedProxy(processedResponse);
     }
-    shouldResolveIncludes(toolName) {
-        return toolName === 'get_fraim_workflow' ||
-            toolName === 'get_fraim_job' ||
-            toolName === 'get_fraim_file' ||
-            toolName === 'seekMentoring';
-    }
-    async resolveIncludesInResponse(response, requestSessionId) {
+    async resolveIncludesInResponse(response, requestSessionId, requestId) {
         if (!response.result?.content || !Array.isArray(response.result.content)) {
             return response;
         }
@@ -807,6 +798,8 @@ class FraimLocalMCPServer {
                 transformedContent.push(block);
                 continue;
             }
+            // resolver.resolveIncludes handles recursion internally via the remoteContentResolver
+            // configured in getRegistryResolver, which correctly uses _doProxyToRemote.
             const resolvedText = await resolver.resolveIncludes(block.text);
             transformedContent.push({
                 ...block,
@@ -821,14 +814,68 @@ class FraimLocalMCPServer {
             }
         };
     }
-    async finalizeToolResponse(request, response, requestSessionId) {
-        let finalizedResponse = response;
+    async finalizeToolResponse(request, response, requestSessionId, requestId) {
         const toolName = request.params?.name;
-        if (request.method === 'tools/call' && typeof toolName === 'string' && this.shouldResolveIncludes(toolName)) {
-            finalizedResponse = await this.resolveIncludesInResponse(finalizedResponse, requestSessionId);
+        const args = request.params?.arguments || {};
+        if (request.method !== 'tools/call' || typeof toolName !== 'string') {
+            return this.processResponseWithHydration(response, requestSessionId);
+        }
+        const projectRoot = this.findProjectRoot();
+        const resolver = projectRoot ? this.getRegistryResolver(requestSessionId) : null;
+        let finalizedResponse = response;
+        // 1. Resolve top-level override if this tool maps to a specific file.
+        if (resolver) {
+            let registryPath = null;
+            if (toolName === 'get_fraim_file')
+                registryPath = args.path;
+            else if (toolName === 'get_fraim_skill')
+                registryPath = await resolver.findRegistryPath('skills', args.skill);
+            else if (toolName === 'get_fraim_job')
+                registryPath = await resolver.findRegistryPath('jobs', args.job);
+            else if (toolName === 'get_fraim_workflow')
+                registryPath = await resolver.findRegistryPath('workflows', args.workflow);
+            if (registryPath) {
+                const localOverride = resolver.hasLocalOverride(registryPath);
+                const remoteFailed = response.error && (response.error.code === -32001 ||
+                    response.error.data?.remoteStatus === 404);
+                if (localOverride || remoteFailed) {
+                    try {
+                        const resolved = await resolver.resolveFile(registryPath);
+                        if (resolved.content) {
+                            const substitutedContent = this.substituteTemplates(resolved.content);
+                            const newResponse = {
+                                ...response,
+                                result: {
+                                    ...response.result,
+                                    content: [{ type: 'text', text: substitutedContent }]
+                                }
+                            };
+                            delete newResponse.error;
+                            finalizedResponse = newResponse;
+                            // Continue to Step 2 to resolve includes within the local override
+                        }
+                    }
+                    catch (error) {
+                        this.log(`[req:${requestId}] Top-level local resolution failed for ${registryPath}: ${error.message}`);
+                    }
+                }
+            }
         }
+        // 2. Resolve includes within the content (for all registry tools)
+        finalizedResponse = await this.resolveIncludesInResponse(finalizedResponse, requestSessionId, requestId);
         return this.processResponseWithHydration(finalizedResponse, requestSessionId);
     }
+    async finalizeLocalToolTextResponse(request, requestSessionId, requestId, text) {
+        const response = {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {
+                content: [{ type: 'text', text }]
+            }
+        };
+        const withResolvedIncludes = await this.resolveIncludesInResponse(response, requestSessionId, requestId);
+        return this.processResponseWithHydration(withResolvedIncludes, requestSessionId);
+    }
     rewriteProxyTokensInText(text) {
         const tokens = new Set();
         const rewritten = text.replace(/\{\{\s*proxy\.([^}]+?)\s*\}\}/g, (_match, proxyPath) => {
@@ -891,12 +938,14 @@ class FraimLocalMCPServer {
                 workspaceRoot: process.cwd(),
                 remoteContentResolver: async (_path) => {
                     throw new Error('No project root available');
-                }
+                },
+                shouldFilter: (content) => this.isStub(content)
             });
         }
         else {
             return new local_registry_resolver_1.LocalRegistryResolver({
                 workspaceRoot: projectRoot,
+                shouldFilter: (content) => this.isStub(content),
                 remoteContentResolver: async (path) => {
                     // Fetch parent content from remote for inheritance
                     this.log(`🔄 Remote content resolver: fetching ${path}`);
@@ -909,12 +958,12 @@ class FraimLocalMCPServer {
                             name: 'get_fraim_file',
                             arguments: {
                                 path,
-                                _internalRaw: true
+                                raw: true
                             }
                         }
                     };
                     this.applyRequestSessionId(request, requestSessionId);
-                    const response = await this.proxyToRemote(request);
+                    const response = await this._doProxyToRemote(request);
                     if (response.error) {
                         this.logError(`❌ Remote content resolver failed: ${response.error.message}`);
                         throw new Error(`Failed to fetch parent: ${response.error.message}`);
@@ -935,69 +984,28 @@ class FraimLocalMCPServer {
         }
     }
     /**
-     * Determine workflow category from workflow name
+     * Check if content is a "stub" indicating local version should be ignored.
      */
-    getWorkflowCategory(workflowName) {
-        // Product development workflows
-        const productWorkflows = [
-            'prep-issue', 'spec', 'design', 'implement', 'test', 'resolve',
-            'prototype', 'refactor', 'iterate-on-pr-comments', 'retrospect'
-        ];
-        // Customer development workflows
-        const customerWorkflows = [
-            'linkedin-outreach', 'customer-interview', 'insight-analysis',
-            'insight-triage', 'interview-preparation', 'strategic-brainstorming',
-            'thank-customers', 'user-survey-dispatch', 'users-to-target', 'weekly-newsletter'
-        ];
-        // Business development workflows
-        const businessWorkflows = [
-            'partnership-outreach', 'investor-pitch', 'create-business-plan',
-            'ideate-business-opportunity', 'price-product'
-        ];
-        if (productWorkflows.includes(workflowName)) {
-            return 'product-building';
-        }
-        else if (customerWorkflows.includes(workflowName)) {
-            return 'customer-development';
-        }
-        else if (businessWorkflows.includes(workflowName)) {
-            return 'business-development';
-        }
-        // Default to product-building for unknown workflows
-        return 'product-building';
+    isStub(content) {
+        return content.includes('<!-- FRAIM_DISCOVERY_STUB -->') ||
+            content.includes('STUB:') ||
+            content.includes('<!-- STUB -->');
     }
     /**
-     * Find local override path for a job name by scanning override roots.
-     * Returns a registry-style path like jobs/<category>/<name>.md when found.
-     */
-    findJobOverridePath(jobName) {
-        const projectRoot = this.findProjectRoot();
-        if (!projectRoot)
-            return null;
-        const candidates = [
-            (0, path_1.join)(projectRoot, '.fraim', 'personalized-employee', 'jobs'),
-            (0, path_1.join)(projectRoot, '.fraim', 'overrides', 'jobs')
-        ];
-        for (const jobsRoot of candidates) {
-            if (!(0, fs_1.existsSync)(jobsRoot))
-                continue;
-            try {
-                const categories = (0, fs_1.readdirSync)(jobsRoot, { withFileTypes: true })
-                    .filter(entry => entry.isDirectory())
-                    .map(entry => entry.name);
-                for (const category of categories) {
-                    const jobFilePath = (0, path_1.join)(jobsRoot, category, `${jobName}.md`);
-                    if ((0, fs_1.existsSync)(jobFilePath)) {
-                        return `jobs/${category}/${jobName}.md`;
-                    }
-                }
-            }
-            catch {
-                // Best effort scan only.
+            if (existsSync(jobFilePath)) {
+              return `jobs/${category}/${jobName}.md`;
             }
+          }
+        } catch {
+          // Best effort scan only.
         }
-        return null;
+      }
+  
+      return null;
     }
+  
+  
+  
     /**
      * Process template substitution in MCP response
      */
@@ -1135,13 +1143,19 @@ class FraimLocalMCPServer {
             request.params.arguments.sessionId = requestSessionId;
         }
     }
+    /**
+     * Get or create a local AI mentor instance for the current session.
+     */
+    getMentor(requestSessionId) {
+        const resolver = this.getRegistryResolver(requestSessionId);
+        return new ai_mentor_1.AIMentor(resolver);
+    }
     normalizeRepoContext(repo) {
         if (!repo || typeof repo !== 'object')
             return repo;
         const normalized = { ...repo };
-        const detectedProvider = (0, provider_utils_1.detectProvider)(normalized.url);
-        if (typeof detectedProvider === 'string' && detectedProvider.length > 0) {
-            normalized.provider = detectedProvider;
+        if (!normalized.provider && normalized.url) {
+            normalized.provider = (0, provider_utils_1.detectProvider)(normalized.url);
         }
         if (normalized.provider !== 'gitlab')
             return normalized;
@@ -1174,10 +1188,11 @@ class FraimLocalMCPServer {
         };
     }
     /**
-     * Proxy request to remote FRAIM server
+     * Internal method to perform the actual proxy request to the remote server.
+     * This method does NOT inject raw: true, as it is used for both top-level
+     * tool calls and recursive inclusion resolution.
      */
-    async proxyToRemote(request) {
-        const requestId = (0, crypto_1.randomUUID)();
+    async _doProxyToRemote(request, requestId = (0, crypto_1.randomUUID)()) {
         let sentFallbackTelemetry = null;
         try {
             // Special handling for fraim_connect - automatically inject machine and repo info
@@ -1191,9 +1206,6 @@ class FraimLocalMCPServer {
                     ...detectedMachine // Detected values override (always win)
                 };
                 this.log(`[req:${requestId}] Auto-detected and injected machine info: ${JSON.stringify(args.machine)}`);
-                if (!args.machine.memory || !args.machine.cpus) {
-                    this.logError(`[req:${requestId}] WARNING: Machine info missing memory or cpus! Detected: ${JSON.stringify(detectedMachine)}, Final: ${JSON.stringify(args.machine)}`);
-                }
                 // REQUIRED: Auto-detect and inject repo info
                 const detectedRepo = this.detectRepoInfo();
                 if (detectedRepo) {
@@ -1239,10 +1251,14 @@ class FraimLocalMCPServer {
                     ...args.repo,
                     ...(args.issueTracking ? { issueTracking: args.issueTracking } : {})
                 };
-                // Keep proxy runtime repository context in sync with connect payload.
+                // Keep proxy runtime context in sync with connect payload.
+                this.agentInfo = args.agent;
+                this.machineInfo = args.machine;
                 this.repoInfo = runtimeRepoContext;
                 if (this.engine) {
-                    this.engine.setRepoInfo(runtimeRepoContext);
+                    this.engine.setAgentInfo(this.agentInfo);
+                    this.engine.setMachineInfo(this.machineInfo);
+                    this.engine.setRepoInfo(this.repoInfo);
                 }
                 // Update the request with injected info
                 request.params.arguments = args;
@@ -1264,7 +1280,12 @@ class FraimLocalMCPServer {
                     .toString('base64');
             }
             this.log(`[req:${requestId}] Proxying ${request.method} to ${this.remoteUrl}/mcp`);
-            const response = await axios_1.default.post(`${this.remoteUrl}/mcp`, request, {
+            // Resolve templates in the outgoing request so the remote server 
+            // only ever sees finalized values.
+            const stringifiedRequest = JSON.stringify(request);
+            const resolvedRequestStr = this.substituteTemplates(stringifiedRequest);
+            const finalRequest = JSON.parse(resolvedRequestStr);
+            const response = await axios_1.default.post(`${this.remoteUrl}/mcp`, finalRequest, {
                 headers,
                 timeout: 30000
             });
@@ -1335,7 +1356,7 @@ class FraimLocalMCPServer {
                 params: {}
             };
             this.log(`📤 Sending roots/list request: ${JSON.stringify(rootsRequest)}`);
-            process.stdout.write(JSON.stringify(rootsRequest) + '\n');
+            this.writer(JSON.stringify(rootsRequest) + '\n');
         }
         catch (error) {
             this.log(`⚠️  Failed to request roots: ${error.message}`);
@@ -1350,6 +1371,7 @@ class FraimLocalMCPServer {
     async handleRequest(request) {
         this.log(`📥 ${request.method}`);
         const requestSessionId = this.extractSessionIdFromRequest(request);
+        const requestId = (0, crypto_1.randomUUID)();
         // Special handling for initialize request
         if (request.method === 'initialize') {
             // Check if client supports roots
@@ -1358,9 +1380,13 @@ class FraimLocalMCPServer {
                 this.clientSupportsRoots = true;
                 this.log(`✅ Client supports roots capability (listChanged: ${clientCapabilities.roots.listChanged})`);
             }
-            // Proxy initialize to remote server first
-            const response = await this.proxyToRemote(request);
-            const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
+            else {
+                this.clientSupportsRoots = false;
+                this.log(`❌ Client does NOT support roots capability`);
+            }
+            // Proxy initialize to remote server first using the raw proxy method
+            const response = await this._doProxyToRemote(request, requestId);
+            const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId, requestId);
             // After successful initialization, load config
             if (!processedResponse.error) {
                 // Load config immediately for compatibility, then request roots so
@@ -1373,160 +1399,90 @@ class FraimLocalMCPServer {
             this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
             return processedResponse;
         }
-        // Intercept get_fraim_workflow, get_fraim_job, and get_fraim_file for override resolution
-        if (request.method === 'tools/call' &&
-            (request.params?.name === 'get_fraim_workflow' ||
-                request.params?.name === 'get_fraim_job' ||
-                request.params?.name === 'get_fraim_file')) {
-            try {
-                const toolName = request.params.name;
-                const args = request.params.arguments || {};
-                // Extract the requested path
-                let requestedPath;
-                if (toolName === 'get_fraim_workflow') {
-                    // Convert workflow name to path (e.g., "spec" -> "workflows/product-building/spec.md")
-                    const workflowName = args.workflow;
-                    if (!workflowName) {
-                        this.log('⚠️ No workflow name provided in get_fraim_workflow');
-                    }
-                    else {
-                        // Determine workflow category from name
-                        const category = this.getWorkflowCategory(workflowName);
-                        requestedPath = `workflows/${category}/${workflowName}.md`;
-                        this.log(`🔍 Checking for override: ${requestedPath}`);
-                        const resolver = this.getRegistryResolver(requestSessionId);
-                        const hasOverride = resolver.hasLocalOverride(requestedPath);
-                        this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
-                        if (hasOverride) {
-                            this.log(`✅ Local override found: ${requestedPath}`);
-                            const resolved = await resolver.resolveFile(requestedPath);
-                            this.log(`📝 Override resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
-                            // Build MCP response with resolved content
-                            const response = {
-                                jsonrpc: '2.0',
-                                id: request.id,
-                                result: {
-                                    content: [
-                                        {
-                                            type: 'text',
-                                            text: resolved.content
-                                        }
-                                    ]
-                                }
-                            };
-                            // Apply template substitution
-                            const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
-                            this.log(`📤 ${request.method} → OK`);
-                            return processedResponse;
-                        }
-                    }
+        // Force ALL tools/call requests to return raw definitions so the proxy
+        // can resolve templates and replace includes locally
+        const toolName = request.params?.name;
+        let injectedRequest = request;
+        if (request.method === 'tools/call' && typeof toolName === 'string') {
+            const args = request.params.arguments || {};
+            // 🔍 SMART DISPATCHER: Intercept mentoring and job/workflow tools for local overrides
+            if (toolName === 'seekMentoring') {
+                try {
+                    const mentor = this.getMentor(requestSessionId);
+                    const tutoringResponse = await mentor.handleMentoringRequest(args);
+                    this.log(`✅ Local seekMentoring succeeded for ${args.workflowType}:${args.currentPhase}`);
+                    return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, tutoringResponse.message);
                 }
-                else if (toolName === 'get_fraim_job') {
-                    const jobName = args.job;
-                    if (!jobName) {
-                        this.log('⚠️ No job name provided in get_fraim_job');
-                    }
-                    else {
-                        // Determine job path by scanning local override roots.
-                        requestedPath = this.findJobOverridePath(jobName) || `jobs/product-building/${jobName}.md`;
-                        this.log(`🔍 Checking for override: ${requestedPath}`);
-                        const resolver = this.getRegistryResolver(requestSessionId);
-                        const hasOverride = resolver.hasLocalOverride(requestedPath);
-                        this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
-                        if (hasOverride) {
-                            this.log(`✅ Local override found: ${requestedPath}`);
-                            const resolved = await resolver.resolveFile(requestedPath);
-                            this.log(`📝 Override resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
-                            const response = {
-                                jsonrpc: '2.0',
-                                id: request.id,
-                                result: {
-                                    content: [
-                                        {
-                                            type: 'text',
-                                            text: resolved.content
-                                        }
-                                    ]
-                                }
-                            };
-                            const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
-                            this.log(`📤 ${request.method} → OK`);
-                            return processedResponse;
+                catch (error) {
+                    this.log(`⚠️ Local seekMentoring failed: ${error.message}. Falling back to remote.`);
+                    // If local fails, we continue to proxy to the remote server
+                }
+            }
+            if (toolName === 'get_fraim_job' || toolName === 'get_fraim_workflow') {
+                const isJob = toolName === 'get_fraim_job';
+                const name = isJob ? args.job : args.workflow;
+                if (name) {
+                    try {
+                        const mentor = this.getMentor(requestSessionId);
+                        const overview = isJob
+                            ? await mentor.getJobOverview(name)
+                            : await mentor.getWorkflowOverview(name);
+                        if (overview) {
+                            this.log(`✅ Local override found for ${toolName}: ${name}`);
+                            let responseText = overview.overview;
+                            if (!overview.isSimple) {
+                                const phaseAuthority = await mentor.getPhaseAuthorityContent();
+                                if (phaseAuthority)
+                                    responseText = `${phaseAuthority}\n\n---\n\n${responseText}`;
+                                responseText += `\n\n---\n\n**This ${isJob ? 'job' : 'workflow'} has phases.** Use \`seekMentoring\` to get phase-specific instructions.`;
+                            }
+                            return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, responseText);
                         }
                     }
-                }
-                else if (toolName === 'get_fraim_file') {
-                    requestedPath = args.path;
-                    if (!requestedPath) {
-                        this.log('⚠️ No path provided in get_fraim_file');
+                    catch (error) {
+                        this.log(`⚠️ Local ${toolName} failed for ${name}: ${error.message}. Falling back to remote.`);
                     }
-                    else {
-                        if (requestedPath.startsWith('providers/')) {
-                            // Server-authoritative templates: never resolve provider files via local overrides.
-                            this.log(`🔒 Skipping local override for provider template file: ${requestedPath}`);
-                        }
-                        else {
-                            this.log(`🔍 Checking for override: ${requestedPath}`);
-                            const resolver = this.getRegistryResolver(requestSessionId);
-                            const isLocalFirstSyncedPath = requestedPath.startsWith('skills/') || requestedPath.startsWith('rules/');
-                            if (isLocalFirstSyncedPath && resolver.hasSyncedLocalFile(requestedPath)) {
-                                this.log(`✅ Synced local file found: ${requestedPath}`);
-                                const resolved = await resolver.resolveFile(requestedPath, { includeMetadata: false });
-                                this.log(`📝 Synced local file resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
-                                const response = {
-                                    jsonrpc: '2.0',
-                                    id: request.id,
-                                    result: {
-                                        content: [
-                                            {
-                                                type: 'text',
-                                                text: resolved.content
-                                            }
-                                        ]
-                                    }
-                                };
-                                const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
-                                this.log(`📤 ${request.method} → OK`);
-                                return processedResponse;
-                            }
-                            const hasOverride = resolver.hasLocalOverride(requestedPath);
-                            this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
-                            if (hasOverride) {
-                                this.log(`✅ Local override found: ${requestedPath}`);
-                                const resolved = await resolver.resolveFile(requestedPath);
-                                this.log(`📝 Override resolved (source: ${resolved.source}, inherited: ${resolved.inherited})`);
-                                // Build MCP response with resolved content
-                                const response = {
-                                    jsonrpc: '2.0',
-                                    id: request.id,
-                                    result: {
-                                        content: [
-                                            {
-                                                type: 'text',
-                                                text: resolved.content
-                                            }
-                                        ]
-                                    }
-                                };
-                                // Apply template substitution
-                                const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
-                                this.log(`📤 ${request.method} → OK`);
-                                return processedResponse;
+                }
+            }
+            // DISCOVERY AGGREGATION: Merge local and remote jobs/workflows
+            if (toolName === 'list_fraim_jobs' || toolName === 'list_fraim_workflows') {
+                const isJob = toolName === 'list_fraim_jobs';
+                const response = await this._doProxyToRemote(request, requestId);
+                if (!response.error && response.result?.content?.[0]?.text) {
+                    try {
+                        const resolver = this.getRegistryResolver(requestSessionId);
+                        const localItems = await resolver.listItems(isJob ? 'job' : 'workflow');
+                        if (localItems.length > 0) {
+                            this.log(`📦 Aggregating ${localItems.length} local ${isJob ? 'jobs' : 'workflows'} into remote response`);
+                            let combinedText = response.result.content[0].text;
+                            combinedText += `\n\n## Local & Personalized ${isJob ? 'Jobs' : 'Workflows'} (.fraim/)\n\n`;
+                            for (const item of localItems) {
+                                combinedText += `- **${item.name}**: ${item.description || '(No description available)'}\n`;
                             }
+                            response.result.content[0].text = combinedText;
                         }
                     }
+                    catch (error) {
+                        this.log(`⚠️ Discovery aggregation failed: ${error.message}`);
+                    }
                 }
+                return response;
             }
-            catch (error) {
-                this.logError(`Override resolution failed: ${error.message}`);
-                this.log('⚠️ Falling back to remote');
-                // Fall through to proxy to remote
-            }
+            // Normal path for other tools: inject raw:true
+            injectedRequest = {
+                ...request,
+                params: {
+                    ...request.params,
+                    arguments: {
+                        ...args,
+                        raw: true
+                    }
+                }
+            };
         }
-        // Proxy to remote server
-        const response = await this.proxyToRemote(request);
-        const processedResponse = await this.finalizeToolResponse(request, response, requestSessionId);
-        this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
+        const response = await this._doProxyToRemote(injectedRequest, requestId);
+        const processedResponse = await this.finalizeToolResponse(injectedRequest, response, requestSessionId, requestId);
+        this.log(`📤 ${injectedRequest.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
         return processedResponse;
     }
     /**
@@ -1549,23 +1505,23 @@ class FraimLocalMCPServer {
                     const firstRoot = roots[0];
                     if (firstRoot.uri && firstRoot.uri.startsWith('file://')) {
                         const rootPath = this.fileUriToLocalPath(firstRoot.uri);
-                        if (!rootPath) {
+                        if (rootPath) {
+                            this.workspaceRoot = rootPath;
+                            this.log(`✅ Got workspace root from client: ${this.workspaceRoot} (${firstRoot.name || 'unknown'})`);
+                            this.loadConfig(); // Reload config with the correct workspace root
+                        }
+                        else {
                             this.log(`⚠️  Could not parse root URI: ${firstRoot.uri}`);
                             this.loadConfig();
-                            return;
                         }
-                        this.log(`✅ Got workspace root from client: ${rootPath} (${firstRoot.name || 'unnamed'})`);
-                        this.workspaceRoot = rootPath;
-                        // Now load config with the correct workspace root
-                        this.loadConfig();
                     }
                     else {
-                        this.log(`⚠️  Root URI is not a file:// URI: ${firstRoot.uri}`);
+                        this.log(`⚠️  Client returned invalid root URI: ${firstRoot.uri}`);
                         this.loadConfig();
                     }
                 }
                 else {
-                    this.log('⚠️  No roots provided by client');
+                    this.log(`⚠️  Client returned empty or invalid roots array`);
                     this.loadConfig();
                 }
             }