fraim 2.0.100

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

@@ -0,0 +1,1698 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * FRAIM Local MCP Server - STDIO Version
+ *
+ * Proxy that:
+ * 1. Accepts MCP requests via stdin/stdout
+ * 2. Proxies to remote FRAIM server
+ * 3. Performs template substitution:
+ *    - Proxy config variables: {{proxy.config.path.to.value}}
+ *    - Platform-specific actions: {{proxy.action.get_issue}}, {{proxy.action.create_pr}}, etc.
+ * 4. Automatically detects and injects machine/repo info for fraim_connect
+ * 5. Substitutes {{proxy.delivery.*}} templates based on user's workingStyle
+ *    (PR or Conversation from ~/.fraim/config.json). Delivery phases live
+ *    server-side in the workflow; the proxy just fills in mode-specific content.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FraimLocalMCPServer = exports.FraimTemplateEngine = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const os_1 = require("os");
+const child_process_1 = require("child_process");
+const crypto_1 = require("crypto");
+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");
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const usage_collector_js_1 = require("./usage-collector.js");
+const learning_context_builder_js_1 = require("./learning-context-builder.js");
+/**
+ * Handle template substitution logic separately for better testability
+ */
+class FraimTemplateEngine {
+    constructor(opts) {
+        this.userEmail = null;
+        this.deliveryTemplatesCache = null;
+        this.providerTemplatesCache = {};
+        this.deliveryTemplatesLoadAttempted = false;
+        this.providerTemplatesLoadAttempted = new Set();
+        this.config = opts.config;
+        this.repoInfo = opts.repoInfo;
+        this.workingStyle = opts.workingStyle;
+        this.projectRoot = opts.projectRoot;
+        this.logFn = opts.logFn || (() => { });
+    }
+    setDeliveryTemplates(templates) {
+        this.deliveryTemplatesCache = templates;
+        this.deliveryTemplatesLoadAttempted = true;
+    }
+    setProviderTemplates(provider, templates) {
+        this.providerTemplatesCache[provider] = templates;
+        this.providerTemplatesLoadAttempted.add(provider);
+    }
+    hasDeliveryTemplates() {
+        return this.deliveryTemplatesCache !== null;
+    }
+    hasProviderTemplates(provider) {
+        return !!this.providerTemplatesCache[provider];
+    }
+    setRepoInfo(repoInfo) {
+        this.repoInfo = repoInfo;
+    }
+    setAgentInfo(info) {
+        this.agentInfo = info;
+    }
+    setMachineInfo(info) {
+        this.machineInfo = info;
+    }
+    setConfig(config) {
+        this.config = config;
+    }
+    setUserEmail(email) {
+        this.userEmail = email;
+    }
+    getUserEmail() {
+        return this.userEmail;
+    }
+    substituteTemplates(content) {
+        let result = content;
+        // Substitute {{proxy.user.email}} with the email captured from fraim_connect
+        if (this.userEmail) {
+            result = result.replace(/\{\{proxy\.user\.email\}\}/g, this.userEmail);
+        }
+        // 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) => {
+            try {
+                if (this.config) {
+                    const value = (0, object_utils_1.getNestedValue)(this.config, path.trim());
+                    if (value !== undefined) {
+                        return typeof value === 'object'
+                            ? JSON.stringify(value)
+                            : String(value);
+                    }
+                }
+                return fallback !== undefined ? fallback : match;
+            }
+            catch (error) {
+                return fallback !== undefined ? fallback : match;
+            }
+        });
+        // Second, substitute {{proxy.delivery.*}} templates
+        const deliveryValues = this.loadDeliveryTemplates();
+        if (deliveryValues) {
+            result = result.replace(/\{\{proxy\.delivery\.([^}]+)\}\}/g, (match, key) => {
+                const value = deliveryValues[`proxy.delivery.${key.trim()}`];
+                return value !== undefined ? value : match;
+            });
+        }
+        // Third, substitute platform-specific action templates
+        result = this.substitutePlatformActions(result);
+        return result;
+    }
+    loadDeliveryTemplates() {
+        if (this.deliveryTemplatesCache)
+            return this.deliveryTemplatesCache;
+        if (this.deliveryTemplatesLoadAttempted)
+            return null;
+        this.deliveryTemplatesLoadAttempted = true;
+        // Server-authoritative mode: runtime templates are hydrated via cache + remote fetch
+        // in FraimLocalMCPServer. Do not read framework/project registry files directly.
+        return null;
+    }
+    substitutePlatformActions(content) {
+        const codeProvider = this.getCodeProvider();
+        const issueProvider = this.getIssueProvider();
+        const codeTemplates = this.loadProviderTemplates(codeProvider);
+        const issueTemplates = issueProvider ? this.loadProviderTemplates(issueProvider) : null;
+        let result = content;
+        if (issueTemplates) {
+            for (const [action, template] of Object.entries(issueTemplates)) {
+                if (!FraimTemplateEngine.ISSUE_ACTIONS.has(action))
+                    continue;
+                const escapedAction = action.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const regex = new RegExp(`\\{\\{${FraimTemplateEngine.PROXY_ACTION_PREFIX}${escapedAction}\\}\\}`, 'g');
+                result = result.replace(regex, this.renderActionTemplate(template));
+            }
+        }
+        if (codeTemplates) {
+            for (const [action, template] of Object.entries(codeTemplates)) {
+                if (issueProvider && issueProvider !== codeProvider && FraimTemplateEngine.ISSUE_ACTIONS.has(action))
+                    continue;
+                const escapedAction = action.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const regex = new RegExp(`\\{\\{${FraimTemplateEngine.PROXY_ACTION_PREFIX}${escapedAction}\\}\\}`, 'g');
+                result = result.replace(regex, this.renderActionTemplate(template));
+            }
+        }
+        return result;
+    }
+    getCodeProvider() {
+        const repoProvider = this.repoInfo?.provider || this.config?.repository?.provider;
+        if (typeof repoProvider === 'string' && repoProvider.trim().length > 0) {
+            return repoProvider;
+        }
+        return (0, provider_utils_1.detectProvider)(this.repoInfo?.url || this.config?.repository?.url);
+    }
+    getIssueProvider() {
+        const fromRepoInfo = this.repoInfo?.issueTracking?.provider;
+        if (typeof fromRepoInfo === 'string' && fromRepoInfo.trim().length > 0) {
+            return fromRepoInfo;
+        }
+        const fromConfig = this.config?.issueTracking?.provider;
+        if (typeof fromConfig === 'string' && fromConfig.trim().length > 0) {
+            return fromConfig;
+        }
+        return null;
+    }
+    loadProviderTemplates(provider) {
+        if (this.providerTemplatesCache[provider])
+            return this.providerTemplatesCache[provider];
+        if (this.providerTemplatesLoadAttempted.has(provider))
+            return null;
+        this.providerTemplatesLoadAttempted.add(provider);
+        // Server-authoritative mode: runtime templates are hydrated via cache + remote fetch
+        // in FraimLocalMCPServer. Do not read framework/project registry files directly.
+        return null;
+    }
+    renderActionTemplate(template) {
+        if (!this.repoInfo && !this.config?.repository && !this.config?.issueTracking) {
+            return template;
+        }
+        return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
+            const trimmedPath = path.trim();
+            // Handle proxy.repository.* variables
+            if (trimmedPath.startsWith('proxy.repository.')) {
+                const repoPath = trimmedPath.substring('proxy.repository.'.length);
+                if (this.repoInfo) {
+                    const value = (0, object_utils_1.getNestedValue)(this.repoInfo, repoPath);
+                    if (value !== undefined)
+                        return String(value);
+                }
+                if (this.config?.repository) {
+                    const value = (0, object_utils_1.getNestedValue)(this.config.repository, repoPath);
+                    if (value !== undefined)
+                        return String(value);
+                }
+            }
+            // Handle proxy.issueTracking.* variables (for split provider mode)
+            if (trimmedPath.startsWith('proxy.issueTracking.')) {
+                const issueTrackingPath = trimmedPath.substring('proxy.issueTracking.'.length);
+                if (this.repoInfo?.issueTracking) {
+                    const value = (0, object_utils_1.getNestedValue)(this.repoInfo.issueTracking, issueTrackingPath);
+                    if (value !== undefined)
+                        return String(value);
+                }
+                if (this.config?.issueTracking) {
+                    const value = (0, object_utils_1.getNestedValue)(this.config.issueTracking, issueTrackingPath);
+                    if (value !== undefined)
+                        return String(value);
+                }
+            }
+            return match;
+        });
+    }
+}
+exports.FraimTemplateEngine = FraimTemplateEngine;
+FraimTemplateEngine.PROXY_ACTION_PREFIX = 'proxy.action.';
+FraimTemplateEngine.ISSUE_ACTIONS = new Set([
+    'get_issue',
+    'update_issue_status',
+    'add_issue_comment',
+    'create_issue',
+    'assign_issue',
+    'search_issues',
+    'close_issue',
+    'list_issues'
+]);
+class FraimLocalMCPServer {
+    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;
+        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();
+        if (!this.apiKey) {
+            this.logError('❌ FRAIM API key is required');
+            this.logError('   Set FRAIM_API_KEY environment variable or add apiKey to ~/.fraim/config.json');
+            process.exit(1);
+        }
+        this.log('🚀 FRAIM Local MCP Server starting... [DEBUG-PROXY-V3]');
+        this.log(`📡 Remote server: ${this.remoteUrl}`);
+        this.log(`🔑 API key: ${this.apiKey.substring(0, 10)}...`);
+        this.log(`Local MCP version: ${this.localVersion}`);
+        this.log(`🔍 DEBUG BUILD: Machine detection v2 active`);
+        // Initialize usage collector
+        this.usageCollector = new usage_collector_js_1.UsageCollector();
+        this.log('📊 Usage analytics collector initialized');
+    }
+    /**
+     * Load API key from environment variable or user config file
+     * Priority: FRAIM_API_KEY env var > ~/.fraim/config.json
+     */
+    loadApiKey() {
+        // First try environment variable (for IDE MCP configs)
+        if (process.env.FRAIM_API_KEY) {
+            return process.env.FRAIM_API_KEY;
+        }
+        // Fallback to user config file
+        try {
+            const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+            if (!homeDir)
+                return '';
+            const configPath = (0, path_1.join)(homeDir, '.fraim', 'config.json');
+            if ((0, fs_1.existsSync)(configPath)) {
+                const config = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+                if (config.apiKey) {
+                    return config.apiKey;
+                }
+            }
+        }
+        catch (error) {
+            // Ignore errors, will fail with clear message below
+        }
+        return '';
+    }
+    log(message) {
+        // Log to stderr (stdout is reserved for MCP protocol)
+        const key = this.apiKey || 'MISSING_API_KEY';
+        console.error(`[FRAIM key:${key}] ${message}`);
+        // Also log to file for debugging
+        try {
+            const fs = require('fs');
+            const logFile = require('path').join(require('os').tmpdir(), 'fraim-mcp-proxy.log');
+            fs.appendFileSync(logFile, `${new Date().toISOString()} [${key}] ${message}\n`);
+        }
+        catch (e) {
+            // Ignore file logging errors
+        }
+    }
+    logError(message) {
+        const key = this.apiKey || 'MISSING_API_KEY';
+        console.error(`[FRAIM ERROR key:${key}] ${message}`);
+    }
+    detectLocalVersion() {
+        const candidates = [
+            (0, path_1.join)(__dirname, '..', '..', '..', 'package.json'),
+            (0, path_1.join)(__dirname, '..', '..', 'package.json')
+        ];
+        for (const pkgPath of candidates) {
+            try {
+                if (!(0, fs_1.existsSync)(pkgPath))
+                    continue;
+                const pkg = JSON.parse((0, fs_1.readFileSync)(pkgPath, 'utf8'));
+                if (typeof pkg.version === 'string' && pkg.version.trim().length > 0) {
+                    return pkg.version;
+                }
+            }
+            catch {
+                // Ignore and try the next candidate
+            }
+        }
+        return 'unknown';
+    }
+    findProjectRoot() {
+        // If we already have workspace root from MCP roots, use it
+        if (this.workspaceRoot) {
+            this.log(`✅ Using workspace root from MCP roots: ${this.workspaceRoot}`);
+            return this.workspaceRoot;
+        }
+        // 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)
+            process.env.WORKSPACE_FOLDER, // VSCode and others
+            process.env.PROJECT_ROOT,
+            process.env.VSCODE_CWD,
+            process.env.INIT_CWD,
+        ];
+        for (const hint of workspaceHints) {
+            if (hint && (0, project_fraim_paths_1.workspaceFraimExists)(hint)) {
+                this.log(`Found ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)()} via workspace env var: ${hint}`);
+                return hint;
+            }
+        }
+        // Priority 2: Search upwards from cwd, but skip home directory
+        let currentDir = process.cwd();
+        const root = (0, path_1.parse)(currentDir).root;
+        const homeDir = process.env.HOME || process.env.USERPROFILE;
+        this.log(`🔍 Starting search from: ${currentDir}`);
+        if (homeDir) {
+            this.log(`🏠 Home directory (will skip): ${homeDir}`);
+        }
+        while (currentDir !== root) {
+            const fraimDir = (0, project_fraim_paths_1.getWorkspaceConfigPath)(currentDir).replace(/[\\/]config\.json$/, '');
+            this.log(`   Checking: ${fraimDir}`);
+            if ((0, fs_1.existsSync)(fraimDir)) {
+                // Skip the home directory FRAIM dir and continue searching for a project-specific one
+                if (homeDir && currentDir === homeDir) {
+                    this.log(`Skipping home directory ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)()}, continuing search...`);
+                    currentDir = (0, path_1.dirname)(currentDir);
+                    continue;
+                }
+                this.log(`Found workspace FRAIM dir at: ${currentDir}`);
+                return currentDir;
+            }
+            currentDir = (0, path_1.dirname)(currentDir);
+        }
+        // Priority 3: Fall back to the home directory .fraim if nothing else found
+        if (homeDir && (0, fs_1.existsSync)((0, path_1.join)(homeDir, '.fraim'))) {
+            this.log(`⚠️  Using home directory .fraim as fallback: ${homeDir}`);
+            return homeDir;
+        }
+        this.log('No workspace FRAIM directory found');
+        return null;
+    }
+    loadConfig() {
+        try {
+            this.log(`📍 Process started from: ${process.cwd()}`);
+            // Try to find the project root by searching for the workspace FRAIM directory
+            const projectDir = this.findProjectRoot() || process.cwd();
+            const configPath = (0, project_fraim_paths_1.getWorkspaceConfigPath)(projectDir);
+            this.log(`🔍 Looking for config at: ${configPath}`);
+            if ((0, fs_1.existsSync)(configPath)) {
+                const configContent = (0, fs_1.readFileSync)(configPath, 'utf8');
+                this.config = JSON.parse(configContent);
+                this.log(`Loaded local ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('config.json')}`);
+            }
+            else {
+                this.config = null;
+                this.log(`No ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('config.json')} found - template substitution disabled`);
+            }
+            if (this.engine) {
+                this.engine.setConfig(this.config);
+            }
+        }
+        catch (error) {
+            this.logError(`Failed to load config: ${error}`);
+            this.config = null;
+            if (this.engine) {
+                this.engine.setConfig(this.config);
+            }
+        }
+    }
+    /**
+     * Automatically detect machine information
+     */
+    detectMachineInfo() {
+        if (this.machineInfo) {
+            this.log(`🔄 Returning cached machine info: ${JSON.stringify(this.machineInfo)}`);
+            return this.machineInfo;
+        }
+        try {
+            this.machineInfo = {
+                hostname: (0, os_1.hostname)(),
+                platform: (0, os_1.platform)(),
+                memory: (0, os_1.totalmem)(),
+                cpus: (0, os_1.cpus)().length
+            };
+            this.log(`✅ Detected machine info: ${JSON.stringify(this.machineInfo)}`);
+            return this.machineInfo;
+        }
+        catch (error) {
+            this.logError(`Failed to detect machine info: ${error}`);
+            return {
+                hostname: 'unknown',
+                platform: 'unknown'
+            };
+        }
+    }
+    /**
+     * Automatically detect repository information from git
+     */
+    detectRepoInfo() {
+        if (this.repoInfo) {
+            return this.repoInfo;
+        }
+        // Ensure config is loaded before trying to detect repo info
+        if (!this.config) {
+            this.loadConfig();
+        }
+        try {
+            const projectDir = this.findProjectRoot() || process.cwd();
+            // Try to get git remote URL
+            let repoUrl = '';
+            try {
+                repoUrl = (0, child_process_1.execSync)('git remote get-url origin', {
+                    cwd: projectDir,
+                    encoding: 'utf8',
+                    stdio: ['pipe', 'pipe', 'pipe']
+                }).trim();
+            }
+            catch (error) {
+                // Fall back to config if git fails
+                repoUrl = this.config?.repository?.url || '';
+            }
+            if (!repoUrl) {
+                this.log('No git repository found and no config available');
+                return null;
+            }
+            // Parse repository identity from URL
+            let name = '';
+            let owner = '';
+            let organization = '';
+            let project = '';
+            let namespace = '';
+            let projectPath = '';
+            const githubMatch = repoUrl.match(/github\.com[\/:]([^\/]+)\/([^\/\.]+)/i);
+            const adoMatch = repoUrl.match(/dev\.azure\.com\/([^\/]+)\/([^\/]+)\/_git\/([^\/]+)/i);
+            const gitlabMatch = repoUrl.match(/gitlab[^\/:]*[\/:]([^?\s#]+?)(?:\.git)?$/i);
+            if (githubMatch) {
+                owner = githubMatch[1];
+                name = githubMatch[2];
+            }
+            else if (adoMatch) {
+                organization = adoMatch[1];
+                project = adoMatch[2];
+                name = adoMatch[3];
+            }
+            else if (gitlabMatch) {
+                projectPath = gitlabMatch[1].replace(/^\/+/, '');
+                const segments = projectPath.split('/').filter(Boolean);
+                name = segments[segments.length - 1] || '';
+                namespace = segments.slice(0, -1).join('/');
+            }
+            else if (this.config?.repository) {
+                // Fall back to config if URL parsing fails
+                owner = this.config.repository.owner || '';
+                name = this.config.repository.name || '';
+                organization = this.config.repository.organization || '';
+                project = this.config.repository.project || '';
+                namespace = this.config.repository.namespace || '';
+                projectPath = this.config.repository.projectPath || (namespace && name ? `${namespace}/${name}` : '');
+            }
+            // Get current branch
+            let branch = '';
+            try {
+                branch = (0, child_process_1.execSync)('git branch --show-current', {
+                    cwd: projectDir,
+                    encoding: 'utf8',
+                    stdio: ['pipe', 'pipe', 'pipe']
+                }).trim();
+            }
+            catch (error) {
+                // Fall back to config default branch if available
+                if (this.config?.repository?.defaultBranch) {
+                    branch = this.config.repository.defaultBranch;
+                }
+            }
+            const repoInfo = {
+                url: repoUrl,
+                name: name || 'unknown',
+                ...(organization && { organization }),
+                ...(project && { project }),
+                ...(namespace && { namespace }),
+                ...(projectPath && { projectPath }),
+                ...(branch && { branch })
+            };
+            if (owner) {
+                repoInfo.owner = owner;
+            }
+            this.repoInfo = repoInfo;
+            const repoLabel = this.repoInfo.owner
+                ? `${this.repoInfo.owner}/${this.repoInfo.name}`
+                : this.repoInfo.projectPath || this.repoInfo.name;
+            this.log(`Detected repo info: ${repoLabel}`);
+            return this.repoInfo;
+        }
+        catch (error) {
+            this.logError(`Failed to detect repo info: ${error}`);
+            return null;
+        }
+    }
+    /**
+     * Get the user's working style preference from ~/.fraim/config.json
+     */
+    getWorkingStyle() {
+        // Workspace config takes precedence over global config
+        if (this.config?.workingStyle) {
+            return this.config.workingStyle;
+        }
+        try {
+            const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+            const configPath = (0, path_1.join)(homeDir, '.fraim', 'config.json');
+            if ((0, fs_1.existsSync)(configPath)) {
+                const config = JSON.parse((0, fs_1.readFileSync)(configPath, 'utf8'));
+                return config.workingStyle || 'PR';
+            }
+        }
+        catch {
+            // Ignore errors, default to PR
+        }
+        return 'PR';
+    }
+    getHomeDir() {
+        const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+        return homeDir || null;
+    }
+    getProviderCachePath(filename) {
+        const homeDir = this.getHomeDir();
+        if (!homeDir)
+            return null;
+        return (0, path_1.join)(homeDir, '.fraim', 'cache', 'registry', 'providers', filename);
+    }
+    readCachedTemplateFile(filename) {
+        try {
+            const cachePath = this.getProviderCachePath(filename);
+            if (!cachePath || !(0, fs_1.existsSync)(cachePath))
+                return null;
+            const content = (0, fs_1.readFileSync)(cachePath, 'utf8');
+            const parsed = JSON.parse(content);
+            if (parsed && typeof parsed === 'object') {
+                this.log(`✅ Loaded template cache: ${cachePath}`);
+                return parsed;
+            }
+        }
+        catch (error) {
+            this.log(`⚠️ Failed to read template cache ${filename}: ${error.message}`);
+        }
+        return null;
+    }
+    writeCachedTemplateFile(filename, templates) {
+        try {
+            const cachePath = this.getProviderCachePath(filename);
+            if (!cachePath)
+                return;
+            (0, fs_1.mkdirSync)((0, path_1.dirname)(cachePath), { recursive: true });
+            (0, fs_1.writeFileSync)(cachePath, JSON.stringify(templates), 'utf8');
+            this.log(`✅ Cached template file: ${cachePath}`);
+        }
+        catch (error) {
+            this.log(`⚠️ Failed to cache template ${filename}: ${error.message}`);
+        }
+    }
+    ensureEngine() {
+        if (!this.engine) {
+            const repoInfo = this.detectRepoInfo();
+            this.engine = new FraimTemplateEngine({
+                config: this.config,
+                repoInfo,
+                workingStyle: this.getWorkingStyle(),
+                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;
+    }
+    collectStrings(value, output) {
+        if (typeof value === 'string') {
+            output.push(value);
+            return;
+        }
+        if (Array.isArray(value)) {
+            value.forEach(item => this.collectStrings(item, output));
+            return;
+        }
+        if (value && typeof value === 'object') {
+            Object.values(value).forEach(item => this.collectStrings(item, output));
+        }
+    }
+    responseContainsDeliveryPlaceholders(response) {
+        if (!response.result)
+            return false;
+        const strings = [];
+        this.collectStrings(response.result, strings);
+        return strings.some(s => /\{\{proxy\.delivery\.[^}]+\}\}/.test(s));
+    }
+    responseHasPotentialProviderPlaceholders(response) {
+        if (!response.result)
+            return false;
+        const strings = [];
+        this.collectStrings(response.result, strings);
+        return strings.some(s => /\{\{proxy\.action\.[^}]+\}\}/.test(s));
+    }
+    async fetchRegistryFileFromServer(path, requestSessionId) {
+        const request = {
+            jsonrpc: '2.0',
+            id: (0, crypto_1.randomUUID)(),
+            method: 'tools/call',
+            params: {
+                name: 'get_fraim_file',
+                arguments: {
+                    path,
+                    raw: true
+                }
+            }
+        };
+        this.applyRequestSessionId(request, requestSessionId);
+        const response = await this._doProxyToRemote(request);
+        if (response.error) {
+            this.log(`⚠️ Failed to fetch registry file ${path}: ${response.error.message}`);
+            return null;
+        }
+        const textBlock = response.result?.content?.find((c) => c.type === 'text');
+        if (!textBlock?.text) {
+            this.log(`⚠️ No text content in registry response for ${path}`);
+            return null;
+        }
+        return textBlock.text;
+    }
+    parseTemplateJson(content, context) {
+        const candidates = [];
+        const trimmed = content.trim();
+        candidates.push(trimmed);
+        // get_fraim_file responses include a markdown header, then a separator line, then file content.
+        const separatorIndex = trimmed.indexOf('\n---\n');
+        if (separatorIndex >= 0) {
+            candidates.push(trimmed.slice(separatorIndex + '\n---\n'.length).trim());
+        }
+        const codeFenceMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+        if (codeFenceMatch?.[1]) {
+            candidates.push(codeFenceMatch[1].trim());
+        }
+        const firstBrace = trimmed.indexOf('{');
+        const lastBrace = trimmed.lastIndexOf('}');
+        if (firstBrace >= 0 && lastBrace > firstBrace) {
+            candidates.push(trimmed.slice(firstBrace, lastBrace + 1));
+        }
+        for (const candidate of candidates) {
+            if (!candidate)
+                continue;
+            try {
+                const parsed = JSON.parse(candidate);
+                if (parsed && typeof parsed === 'object') {
+                    return parsed;
+                }
+            }
+            catch {
+                // Try the next extraction candidate.
+            }
+        }
+        this.log(`⚠️ Failed to parse ${context}: no valid JSON object found in response`);
+        return null;
+    }
+    async ensureDeliveryTemplatesAvailable(response, requestSessionId) {
+        if (!this.responseContainsDeliveryPlaceholders(response))
+            return;
+        const engine = this.ensureEngine();
+        if (engine.hasDeliveryTemplates())
+            return;
+        if (engine.loadDeliveryTemplates())
+            return;
+        const filename = this.getWorkingStyle() === 'Conversation'
+            ? 'delivery-conversation.json'
+            : 'delivery-pr.json';
+        const cached = this.readCachedTemplateFile(filename);
+        if (cached) {
+            engine.setDeliveryTemplates(cached);
+            return;
+        }
+        const remoteContent = await this.fetchRegistryFileFromServer(`providers/${filename}`, requestSessionId);
+        if (!remoteContent)
+            return;
+        const parsed = this.parseTemplateJson(remoteContent, `providers/${filename}`);
+        if (!parsed)
+            return;
+        engine.setDeliveryTemplates(parsed);
+        this.writeCachedTemplateFile(filename, parsed);
+    }
+    async ensureProviderTemplatesAvailable(response, requestSessionId) {
+        const hasDirectProviderPlaceholders = this.responseHasPotentialProviderPlaceholders(response);
+        const hasDeliveryPlaceholders = this.responseContainsDeliveryPlaceholders(response);
+        if (!hasDirectProviderPlaceholders && !hasDeliveryPlaceholders)
+            return;
+        const engine = this.ensureEngine();
+        const codeProvider = engine.getCodeProvider();
+        const issueProvider = engine.getIssueProvider();
+        const providers = Array.from(new Set([codeProvider, issueProvider].filter((provider) => typeof provider === 'string' && provider.length > 0)));
+        for (const provider of providers) {
+            if (engine.hasProviderTemplates(provider))
+                continue;
+            if (engine.loadProviderTemplates(provider))
+                continue;
+            const filename = `${provider}.json`;
+            const cached = this.readCachedTemplateFile(filename);
+            if (cached) {
+                engine.setProviderTemplates(provider, cached);
+                continue;
+            }
+            const remoteContent = await this.fetchRegistryFileFromServer(`providers/${filename}`, requestSessionId);
+            if (remoteContent) {
+                const parsed = this.parseTemplateJson(remoteContent, `providers/${filename}`);
+                if (parsed) {
+                    engine.setProviderTemplates(provider, parsed);
+                    this.writeCachedTemplateFile(filename, parsed);
+                }
+            }
+        }
+    }
+    async hydrateTemplateCachesForResponse(response, requestSessionId) {
+        if (!response.result)
+            return;
+        await this.ensureDeliveryTemplatesAvailable(response, requestSessionId);
+        await this.ensureProviderTemplatesAvailable(response, requestSessionId);
+    }
+    async processResponseWithHydration(response, requestSessionId) {
+        await this.hydrateTemplateCachesForResponse(response, requestSessionId);
+        let processedResponse = this.processResponse(response);
+        // Delivery substitution can introduce provider action placeholders (e.g. {{proxy.action.update_issue_status}})
+        // that were not visible pre-substitution. Run one targeted re-hydration pass if needed.
+        const engine = this.ensureEngine();
+        const codeProvider = engine.getCodeProvider();
+        const issueProvider = engine.getIssueProvider();
+        const providers = Array.from(new Set([codeProvider, issueProvider].filter((provider) => typeof provider === 'string' && provider.length > 0)));
+        const hasMissingProviderTemplate = providers.some((provider) => !engine.hasProviderTemplates(provider));
+        if (this.responseHasPotentialProviderPlaceholders(processedResponse) && hasMissingProviderTemplate) {
+            await this.ensureProviderTemplatesAvailable(processedResponse, requestSessionId);
+            processedResponse = this.processResponse(processedResponse);
+        }
+        return this.applyAgentFallbackForUnresolvedProxy(processedResponse);
+    }
+    async resolveIncludesInResponse(response, requestSessionId, requestId) {
+        if (!response.result?.content || !Array.isArray(response.result.content)) {
+            return response;
+        }
+        const resolver = this.getRegistryResolver(requestSessionId);
+        const transformedContent = [];
+        for (const block of response.result.content) {
+            if (block?.type !== 'text' || typeof block.text !== 'string') {
+                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,
+                text: resolvedText
+            });
+        }
+        return {
+            ...response,
+            result: {
+                ...response.result,
+                content: transformedContent
+            }
+        };
+    }
+    async finalizeToolResponse(request, response, requestSessionId, requestId) {
+        const toolName = request.params?.name;
+        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);
+            if (registryPath) {
+                const localOverride = resolver.hasLocalOverride(registryPath);
+                const remoteFailed = Boolean(response.error);
+                if (response.error) {
+                    this.log(`[req:${requestId}] Remote error for ${registryPath}: code=${response.error.code}`);
+                }
+                if (localOverride || remoteFailed) {
+                    try {
+                        // personalized-employee/ takes priority; when remote fails, resolver falls back to synced/cached content
+                        const resolved = await resolver.resolveFile(registryPath).catch(() => null);
+                        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;
+                        }
+                    }
+                    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);
+        // 3. After fraim_connect succeeds, capture user email and inject learning context.
+        if (toolName === 'fraim_connect' && !finalizedResponse.error) {
+            const text = finalizedResponse.result?.content?.[0]?.text;
+            if (typeof text === 'string') {
+                const emailMatch = text.match(/Your identity for this session: \*\*([^*]+)\*\*/);
+                if (emailMatch) {
+                    const userEmail = emailMatch[1].trim();
+                    this.ensureEngine().setUserEmail(userEmail);
+                    this.log(`[req:${requestId}] Captured user email for template substitution: ${userEmail}`);
+                    // Inject learning context from the local workspace (RFC 177: files live on disk, not server).
+                    const workspaceRoot = this.findProjectRoot() || process.cwd();
+                    const learningSection = (0, learning_context_builder_js_1.buildLearningContextSection)(workspaceRoot, userEmail, false);
+                    if (learningSection) {
+                        finalizedResponse.result.content[0].text = text + learningSection;
+                        this.log(`[req:${requestId}] Injected learning context for ${userEmail} from ${workspaceRoot}`);
+                    }
+                }
+            }
+        }
+        // 4. After get_fraim_job succeeds, inject learning context with job-focus frame.
+        if (toolName === 'get_fraim_job' && !finalizedResponse.error) {
+            const text = finalizedResponse.result?.content?.[0]?.text;
+            const userEmail = this.ensureEngine().getUserEmail();
+            if (typeof text === 'string' && userEmail) {
+                const workspaceRoot = this.findProjectRoot() || process.cwd();
+                const learningSection = (0, learning_context_builder_js_1.buildLearningContextSection)(workspaceRoot, userEmail, true);
+                if (learningSection) {
+                    finalizedResponse.result.content[0].text = text + `\n\n---` + learningSection;
+                    this.log(`[req:${requestId}] Injected job-focus learning context for ${userEmail}`);
+                }
+            }
+        }
+        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) => {
+            const normalized = proxyPath.trim();
+            tokens.add(`proxy.${normalized}`);
+            return `{{agent.${normalized}}}`;
+        });
+        if (tokens.size === 0) {
+            return { text, tokens: [] };
+        }
+        const hasResolutionNotice = rewritten.includes('## Agent Resolution Needed');
+        const finalText = hasResolutionNotice
+            ? rewritten
+            : `${FraimLocalMCPServer.AGENT_RESOLUTION_NOTICE}\n\n${rewritten}`;
+        return { text: finalText, tokens: Array.from(tokens).sort() };
+    }
+    rewriteUnresolvedProxyPlaceholders(value) {
+        const rewrittenTokens = new Set();
+        const rewrite = (input) => {
+            if (typeof input === 'string') {
+                const rewritten = this.rewriteProxyTokensInText(input);
+                rewritten.tokens.forEach((token) => rewrittenTokens.add(token));
+                return rewritten.text;
+            }
+            if (Array.isArray(input)) {
+                return input.map(rewrite);
+            }
+            if (input && typeof input === 'object') {
+                const output = {};
+                for (const [key, nestedValue] of Object.entries(input)) {
+                    if (key === 'text' && typeof nestedValue === 'string') {
+                        const rewritten = this.rewriteProxyTokensInText(nestedValue);
+                        rewritten.tokens.forEach((token) => rewrittenTokens.add(token));
+                        output[key] = rewritten.text;
+                    }
+                    else {
+                        output[key] = rewrite(nestedValue);
+                    }
+                }
+                return output;
+            }
+            return input;
+        };
+        const rewrittenValue = rewrite(value);
+        return { value: rewrittenValue, tokens: Array.from(rewrittenTokens).sort() };
+    }
+    substituteTemplates(content) {
+        return this.ensureEngine().substituteTemplates(content);
+    }
+    /**
+     * Initialize the LocalRegistryResolver for override resolution
+     */
+    getRegistryResolver(requestSessionId) {
+        const projectRoot = this.findProjectRoot();
+        this.log(`🔍 getRegistryResolver: projectRoot = ${projectRoot}`);
+        if (!projectRoot) {
+            this.log('⚠️ No project root found, override resolution disabled');
+            // Return a resolver that always falls back to remote
+            return new local_registry_resolver_1.LocalRegistryResolver({
+                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}`);
+                    this.log(`🔄 Fetching raw file content: ${path}`);
+                    const request = {
+                        jsonrpc: '2.0',
+                        id: (0, crypto_1.randomUUID)(),
+                        method: 'tools/call',
+                        params: {
+                            name: 'get_fraim_file',
+                            arguments: {
+                                path,
+                                raw: true
+                            }
+                        }
+                    };
+                    this.applyRequestSessionId(request, requestSessionId);
+                    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}`);
+                    }
+                    // Extract content from MCP response format
+                    if (response.result?.content && Array.isArray(response.result.content)) {
+                        const textContent = response.result.content.find((c) => c.type === 'text');
+                        if (textContent?.text) {
+                            this.log(`✅ Remote content resolver: fetched ${textContent.text.length} chars`);
+                            return textContent.text;
+                        }
+                    }
+                    this.logError(`❌ Remote content resolver: no content in response for ${path}`);
+                    this.logError(`Response: ${JSON.stringify(response, null, 2)}`);
+                    throw new Error(`No content in remote response for ${path}`);
+                }
+            });
+        }
+    }
+    /**
+     * Check if content is a "stub" indicating local version should be ignored.
+     */
+    isStub(content) {
+        return content.includes('<!-- FRAIM_DISCOVERY_STUB -->') ||
+            content.includes('STUB:') ||
+            content.includes('<!-- STUB -->');
+    }
+    /**
+            if (existsSync(jobFilePath)) {
+              return `jobs/${category}/${jobName}.md`;
+            }
+          }
+        } catch {
+          // Best effort scan only.
+        }
+      }
+  
+      return null;
+    }
+  
+  
+  
+    /**
+     * Process template substitution in MCP response
+     */
+    processResponse(response) {
+        if (!response.result)
+            return response;
+        // Recursively substitute templates in all string values
+        const processValue = (value) => {
+            if (typeof value === 'string') {
+                return this.substituteTemplates(value);
+            }
+            else if (Array.isArray(value)) {
+                return value.map(processValue);
+            }
+            else if (value && typeof value === 'object') {
+                const processed = {};
+                for (const [key, val] of Object.entries(value)) {
+                    processed[key] = processValue(val);
+                }
+                return processed;
+            }
+            return value;
+        };
+        return {
+            ...response,
+            result: processValue(response.result)
+        };
+    }
+    applyAgentFallbackForUnresolvedProxy(response) {
+        if (!response.result)
+            return response;
+        const rewritten = this.rewriteUnresolvedProxyPlaceholders(response.result);
+        if (rewritten.tokens.length > 0) {
+            this.logError(`[${FraimLocalMCPServer.FALLBACK_ALERT_MARKER}] Rewrote unresolved proxy placeholders to agent placeholders: ${rewritten.tokens.join(', ')}`);
+        }
+        return {
+            ...response,
+            result: rewritten.value
+        };
+    }
+    extractSessionIdFromRequest(request) {
+        const sessionIdFromParams = request.params?.sessionId;
+        if (typeof sessionIdFromParams === 'string' && sessionIdFromParams.trim().length > 0) {
+            return sessionIdFromParams.trim();
+        }
+        const sessionIdFromArgs = request.params?.arguments?.sessionId;
+        if (typeof sessionIdFromArgs === 'string' && sessionIdFromArgs.trim().length > 0) {
+            return sessionIdFromArgs.trim();
+        }
+        return null;
+    }
+    applyRequestSessionId(request, requestSessionId) {
+        if (!requestSessionId || requestSessionId.trim().length === 0)
+            return;
+        request.params = request.params || {};
+        if (typeof request.params.sessionId !== 'string' || request.params.sessionId.trim().length === 0) {
+            request.params.sessionId = requestSessionId;
+        }
+        request.params.arguments = request.params.arguments || {};
+        if (typeof request.params.arguments.sessionId !== 'string' || request.params.arguments.sessionId.trim().length === 0) {
+            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 };
+        if (!normalized.provider && normalized.url) {
+            normalized.provider = (0, provider_utils_1.detectProvider)(normalized.url);
+        }
+        if (normalized.provider !== 'gitlab')
+            return normalized;
+        if (!normalized.projectPath && typeof normalized.url === 'string') {
+            const gitlabMatch = normalized.url.match(/gitlab[^\/:]*[\/:]([^?\s#]+?)(?:\.git)?$/i);
+            if (gitlabMatch) {
+                normalized.projectPath = gitlabMatch[1].replace(/^\/+/, '');
+            }
+        }
+        if (!normalized.name && typeof normalized.projectPath === 'string') {
+            const segments = normalized.projectPath.split('/').filter(Boolean);
+            normalized.name = segments[segments.length - 1] || normalized.name;
+            normalized.namespace = normalized.namespace || segments.slice(0, -1).join('/');
+        }
+        if (normalized.projectPath || !normalized.namespace || !normalized.name)
+            return normalized;
+        normalized.projectPath = `${normalized.namespace}/${normalized.name}`;
+        return normalized;
+    }
+    normalizeIssueTrackingContext(issueTracking) {
+        if (!issueTracking || typeof issueTracking !== 'object')
+            return issueTracking;
+        if (issueTracking.provider !== 'gitlab')
+            return issueTracking;
+        if (issueTracking.projectPath || !issueTracking.namespace || !issueTracking.name)
+            return issueTracking;
+        return {
+            ...issueTracking,
+            projectPath: `${issueTracking.namespace}/${issueTracking.name}`
+        };
+    }
+    /**
+     * 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 _doProxyToRemote(request, requestId = (0, crypto_1.randomUUID)()) {
+        try {
+            // Special handling for fraim_connect - automatically inject machine and repo info
+            if (request.method === 'tools/call' && request.params?.name === 'fraim_connect') {
+                this.log(`[req:${requestId}] Intercepting fraim_connect to inject machine/repo info`);
+                const args = request.params.arguments || {};
+                // REQUIRED: Auto-detect and inject machine info
+                const detectedMachine = this.detectMachineInfo();
+                args.machine = {
+                    ...args.machine, // Agent values as fallback
+                    ...detectedMachine // Detected values override (always win)
+                };
+                this.log(`[req:${requestId}] Auto-detected and injected machine info: ${JSON.stringify(args.machine)}`);
+                // REQUIRED: Auto-detect and inject repo info
+                const detectedRepo = this.detectRepoInfo();
+                if (detectedRepo) {
+                    args.repo = {
+                        ...args.repo, // Agent values as fallback
+                        ...detectedRepo // Detected values override (always win)
+                    };
+                    args.repo = this.normalizeRepoContext(args.repo);
+                    const repoLabel = args.repo.owner ? `${args.repo.owner}/${args.repo.name}` : args.repo.name;
+                    this.log(`[req:${requestId}] Auto-detected and injected repo info: ${repoLabel}`);
+                }
+                else {
+                    // If detection fails, use agent-provided values (if any)
+                    if (!args.repo || !args.repo.url) {
+                        // Only return error if agent didn't provide repo info either
+                        this.logError(`[req:${requestId}] Could not detect repo info and no repo info provided by agent`);
+                        return {
+                            jsonrpc: '2.0',
+                            id: request.id,
+                            error: {
+                                code: -32603,
+                                message: `Failed to detect repository information. Please ensure you are in a git repository or have ${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('config.json')} configured with repository details, or provide repo info in fraim_connect arguments.`
+                            }
+                        };
+                    }
+                    args.repo = this.normalizeRepoContext(args.repo);
+                    const repoLabel = args.repo.owner ? `${args.repo.owner}/${args.repo.name}` : args.repo.name;
+                    this.log(`[req:${requestId}] Using agent-provided repo info: ${repoLabel}`);
+                }
+                const configuredIssueTracking = this.config?.issueTracking;
+                if (configuredIssueTracking && typeof configuredIssueTracking === 'object') {
+                    args.issueTracking = {
+                        ...(args.issueTracking || {}),
+                        ...configuredIssueTracking
+                    };
+                    args.issueTracking = this.normalizeIssueTrackingContext(args.issueTracking);
+                    this.log(`[req:${requestId}] Applied issueTracking context: ${args.issueTracking.provider || 'unknown'}`);
+                }
+                else if (args.issueTracking) {
+                    args.issueTracking = this.normalizeIssueTrackingContext(args.issueTracking);
+                }
+                const runtimeRepoContext = {
+                    ...args.repo,
+                    ...(args.issueTracking ? { issueTracking: args.issueTracking } : {})
+                };
+                // 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.setAgentInfo(this.agentInfo);
+                    this.engine.setMachineInfo(this.machineInfo);
+                    this.engine.setRepoInfo(this.repoInfo);
+                }
+                // In a proxy setup, the remote server resolves the API key ID during event upload.
+                // No local resolution needed.
+                // Update the request with injected info
+                request.params.arguments = args;
+            }
+            const headers = {
+                'Content-Type': 'application/json',
+                'x-api-key': this.apiKey,
+                'x-fraim-request-id': requestId,
+                'x-fraim-local-version': this.localVersion
+            };
+            const sessionId = this.extractSessionIdFromRequest(request);
+            if (sessionId) {
+                headers[FraimLocalMCPServer.SESSION_HEADER] = sessionId;
+            }
+            this.log(`[req:${requestId}] Proxying ${request.method} to ${this.remoteUrl}/mcp`);
+            // 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
+            });
+            return response.data;
+        }
+        catch (error) {
+            const status = error?.response?.status;
+            const remoteData = error?.response?.data;
+            this.logError(`[req:${requestId}] Remote request failed (${status || 'no-status'}): ${error.message}`);
+            if (remoteData && typeof remoteData === 'object') {
+                const forwarded = {
+                    jsonrpc: typeof remoteData.jsonrpc === 'string' ? remoteData.jsonrpc : '2.0',
+                    id: remoteData.id ?? request.id,
+                    error: remoteData.error ?? {
+                        code: -32603,
+                        message: `Remote server error (${status || 'unknown status'}): ${error.message}`
+                    }
+                };
+                if (forwarded.error && typeof forwarded.error === 'object') {
+                    const existingData = forwarded.error.data;
+                    forwarded.error.data = {
+                        ...(existingData && typeof existingData === 'object' ? existingData : {}),
+                        fraimRequestId: requestId,
+                        remoteStatus: status ?? null,
+                        localMcpVersion: this.localVersion
+                    };
+                }
+                return forwarded;
+            }
+            return {
+                jsonrpc: '2.0',
+                id: request.id || null,
+                error: {
+                    code: status === 401 ? -32001 : -32603,
+                    message: `Remote server error (${status || 'unknown status'}): ${error.message}`,
+                    data: {
+                        fraimRequestId: requestId,
+                        remoteStatus: status ?? null,
+                        localMcpVersion: this.localVersion,
+                        remoteError: remoteData
+                    }
+                }
+            };
+        }
+    }
+    /**
+     * Try to request workspace roots from MCP client
+     */
+    requestRootsFromClient() {
+        if (!this.clientSupportsRoots || this.pendingRootsRequest) {
+            return;
+        }
+        try {
+            this.log('🔍 Requesting workspace roots from client...');
+            this.pendingRootsRequest = true;
+            // Send roots/list request to client via stdout
+            const rootsRequest = {
+                jsonrpc: '2.0',
+                id: 'fraim-roots-query',
+                method: 'roots/list',
+                params: {}
+            };
+            this.log(`📤 Sending roots/list request: ${JSON.stringify(rootsRequest)}`);
+            this.writer(JSON.stringify(rootsRequest) + '\n');
+        }
+        catch (error) {
+            this.log(`⚠️  Failed to request roots: ${error.message}`);
+            this.pendingRootsRequest = false;
+            // Fall back to env var search
+            this.loadConfig();
+        }
+    }
+    /**
+     * Handle incoming MCP request
+     */
+    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
+            const clientCapabilities = request.params?.capabilities;
+            if (clientCapabilities?.roots) {
+                this.clientSupportsRoots = true;
+                this.log(`✅ Client supports roots capability (listChanged: ${clientCapabilities.roots.listChanged})`);
+            }
+            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
+                // workspace-aware clients (Codex, Cursor, etc.) can provide exact roots.
+                this.loadConfig();
+                if (this.clientSupportsRoots) {
+                    setImmediate(() => this.requestRootsFromClient());
+                }
+            }
+            this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : '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;
+        const args = request.params?.arguments || {};
+        let injectedRequest = request;
+        if (request.method === 'tools/call' && typeof toolName === 'string') {
+            // 🔍 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.jobName}:${args.currentPhase}`);
+                    return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, tutoringResponse.message);
+                }
+                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') {
+                const name = args.job;
+                if (name) {
+                    try {
+                        const mentor = this.getMentor(requestSessionId);
+                        const overview = await mentor.getJobOverview(name);
+                        if (overview) {
+                            this.log(`✅ Local override found for get_fraim_job: ${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 job has phases.** Use \`seekMentoring\` to get phase-specific instructions.`;
+                            }
+                            // Inject local learning context for job requests (RFC 177).
+                            const userEmail = this.ensureEngine().getUserEmail();
+                            if (userEmail) {
+                                const workspaceRoot = this.findProjectRoot() || process.cwd();
+                                const learningSection = (0, learning_context_builder_js_1.buildLearningContextSection)(workspaceRoot, userEmail, true);
+                                if (learningSection) {
+                                    responseText += `\n\n---` + learningSection;
+                                    this.log(`✅ Injected job-focus learning context for ${userEmail} (local override path)`);
+                                }
+                            }
+                            return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, responseText);
+                        }
+                    }
+                    catch (error) {
+                        this.log(`⚠️ Local get_fraim_job failed for ${name}: ${error.message}. Falling back to remote.`);
+                    }
+                }
+            }
+            // DISCOVERY AGGREGATION: Merge local and remote jobs
+            if (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('job');
+                        if (localItems.length > 0) {
+                            this.log(`📦 Aggregating ${localItems.length} local jobs into remote response`);
+                            let combinedText = response.result.content[0].text;
+                            combinedText += `\n\n## Local & Personalized Jobs (${(0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)()})\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;
+            }
+            // Normal path for other tools: inject raw:true
+            injectedRequest = {
+                ...request,
+                params: {
+                    ...request.params,
+                    arguments: {
+                        ...args,
+                        raw: true
+                    }
+                }
+            };
+        }
+        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;
+    }
+    /**
+     * Handle incoming MCP response (to our roots/list request)
+     */
+    handleResponse(response) {
+        // Check if this is a response to our roots/list request
+        if (response.id === 'fraim-roots-query') {
+            this.log(`📥 Response to roots/list request`);
+            this.pendingRootsRequest = false;
+            if (response.error) {
+                this.log(`⚠️  Client returned error for roots/list: ${response.error.message}`);
+                // Fall back to env var + upward search
+                this.loadConfig();
+            }
+            else {
+                const roots = response.result?.roots;
+                if (roots && Array.isArray(roots) && roots.length > 0) {
+                    // Use the first root (typically the primary workspace folder)
+                    const firstRoot = roots[0];
+                    if (firstRoot.uri && firstRoot.uri.startsWith('file://')) {
+                        const rootPath = this.fileUriToLocalPath(firstRoot.uri);
+                        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();
+                        }
+                    }
+                    else {
+                        this.log(`⚠️  Client returned invalid root URI: ${firstRoot.uri}`);
+                        this.loadConfig();
+                    }
+                }
+                else {
+                    this.log(`⚠️  Client returned empty or invalid roots array`);
+                    this.loadConfig();
+                }
+            }
+        }
+    }
+    /**
+     * Convert a file:// URI to a local filesystem path.
+     */
+    fileUriToLocalPath(uri) {
+        if (!uri.startsWith('file://'))
+            return null;
+        let pathname = '';
+        let host = '';
+        try {
+            const parsed = new URL(uri);
+            if (parsed.protocol !== 'file:')
+                return null;
+            pathname = parsed.pathname || '';
+            host = parsed.host || '';
+        }
+        catch {
+            const raw = uri.replace('file://', '');
+            try {
+                pathname = decodeURIComponent(raw);
+            }
+            catch {
+                pathname = raw;
+            }
+        }
+        try {
+            pathname = decodeURIComponent(pathname);
+        }
+        catch {
+            // Keep raw path if decoding fails
+        }
+        let localPath = pathname;
+        if (host && host !== 'localhost') {
+            localPath = `//${host}${localPath}`;
+        }
+        // Windows drive letters can arrive as /C:/... or /c:/... or decoded from /c%3A/...
+        localPath = localPath.replace(/^\/([a-zA-Z]:)/, '$1');
+        if (process.platform === 'win32') {
+            localPath = localPath.replace(/\//g, '\\');
+        }
+        return localPath;
+    }
+    /**
+     * Start STDIO server
+     */
+    start() {
+        let buffer = '';
+        process.stdin.setEncoding('utf8');
+        // Set up periodic usage data upload
+        const uploadInterval = setInterval(() => {
+            this.uploadUsageData().catch(error => {
+                this.log(`⚠️ Failed to upload usage data: ${error.message}`);
+            });
+        }, 60000); // Upload every minute
+        // Clean up interval on shutdown
+        const cleanup = () => {
+            clearInterval(uploadInterval);
+            this.usageCollector.shutdown();
+        };
+        process.stdin.on('data', async (chunk) => {
+            buffer += chunk;
+            // Process complete JSON-RPC messages (newline-delimited)
+            let newlineIndex;
+            while ((newlineIndex = buffer.indexOf('\n')) !== -1) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                if (line) {
+                    try {
+                        const message = JSON.parse(line);
+                        // Distinguish between requests and responses
+                        // Requests have 'method', responses have 'result' or 'error' (but no 'method')
+                        if ('method' in message && message.method) {
+                            // This is a request from the client
+                            const response = await this.handleRequest(message);
+                            // Only send response if we got one (null means we handled it internally)
+                            if (response) {
+                                // Collect usage for all tools/call requests before sending response
+                                this.collectUsageForResponse(message, response);
+                                process.stdout.write(JSON.stringify(response) + '\n');
+                            }
+                        }
+                        else if ('result' in message || 'error' in message) {
+                            // This is a response from the client (to our roots/list request)
+                            this.handleResponse(message);
+                            // Don't send anything back - this was a response to our request
+                        }
+                        else {
+                            this.logError(`Unknown message type: ${JSON.stringify(message)}`);
+                            process.stdout.write(JSON.stringify({
+                                jsonrpc: '2.0',
+                                error: {
+                                    code: -32600,
+                                    message: 'Invalid Request: Unknown message type'
+                                },
+                                id: message.id || null
+                            }) + '\n');
+                        }
+                    }
+                    catch (error) {
+                        this.logError(`Message processing failed: ${error.message}`);
+                        // Send error response
+                        const errorResponse = {
+                            jsonrpc: '2.0',
+                            error: {
+                                code: -32700,
+                                message: `Parse error: ${error.message}`
+                            },
+                            id: null
+                        };
+                        process.stdout.write(JSON.stringify(errorResponse) + '\n');
+                    }
+                }
+            }
+        });
+        process.stdin.on('end', () => {
+            this.log('🛑 Stdin closed, shutting down...');
+            cleanup();
+            process.exit(0);
+        });
+        process.on('SIGTERM', () => {
+            this.log('🛑 SIGTERM received, shutting down...');
+            cleanup();
+            process.exit(0);
+        });
+        process.on('SIGINT', () => {
+            this.log('🛑 SIGINT received, shutting down...');
+            cleanup();
+            process.exit(0);
+        });
+        this.log('✅ FRAIM Local MCP Server ready');
+    }
+    /**
+     * Collect usage analytics for tools/call requests
+     */
+    collectUsageForResponse(request, response) {
+        // Only collect usage for tools/call requests
+        if (request.method !== 'tools/call') {
+            return;
+        }
+        const toolName = request.params?.name;
+        const args = request.params?.arguments || {};
+        const requestSessionId = this.extractSessionIdFromRequest(request);
+        if (toolName && requestSessionId) {
+            const success = !response.error;
+            this.log(`📊 Collecting usage: ${toolName} (session: ${requestSessionId}, success: ${success})`);
+            // Capture the current queue size before collection
+            const beforeCount = this.usageCollector.getEventCount();
+            try {
+                this.usageCollector.collectMCPCall(toolName, args, requestSessionId, success);
+                // Check if the event was actually added to the queue
+                const afterCount = this.usageCollector.getEventCount();
+                if (afterCount > beforeCount) {
+                    this.log(`📊 ✅ Event queued successfully (queue: ${afterCount})`);
+                }
+                else {
+                    this.log(`📊 ⚠️ Event not queued - tool may not be tracked: ${toolName}`);
+                    // Log the args for debugging path parsing issues
+                    if (toolName === 'get_fraim_file' && args.path) {
+                        this.log(`📊 🔍 Debug: get_fraim_file path="${args.path}"`);
+                    }
+                }
+            }
+            catch (error) {
+                this.log(`📊 ❌ Usage collection error: ${error.message}`);
+            }
+        }
+        else if (request.method === 'tools/call') {
+            this.log(`⚠️ Skipping usage collection: toolName=${toolName}, sessionId=${requestSessionId}`);
+        }
+    }
+    /**
+     * Flush collected usage data to the remote server
+     */
+    async uploadUsageData() {
+        const eventCount = this.usageCollector.getEventCount();
+        this.log(`📊 Upload check: ${eventCount} events queued`);
+        if (eventCount === 0) {
+            return; // Nothing to flush
+        }
+        try {
+            this.log(`📊 Attempting to flush ${eventCount} events to ${this.remoteUrl}/api/analytics/events`);
+            await this.usageCollector.flush(this.remoteUrl, this.apiKey);
+            this.log(`📊 ✅ Successfully flushed ${eventCount} usage events to remote server`);
+        }
+        catch (error) {
+            this.log(`📊 ❌ Usage flushing error: ${error.message}`);
+            // Log additional details for debugging
+            if (error.response) {
+                this.log(`📊 🔍 HTTP Status: ${error.response.status}, Data: ${JSON.stringify(error.response.data)}`);
+            }
+        }
+    }
+}
+exports.FraimLocalMCPServer = FraimLocalMCPServer;
+FraimLocalMCPServer.AGENT_RESOLUTION_NOTICE = [
+    '## Agent Resolution Needed',
+    'Replace all `agent.*` placeholders with the best value from repository context, user intent, and available project config.'
+].join('\n');
+FraimLocalMCPServer.FALLBACK_ALERT_MARKER = 'PROXY_FALLBACK_ALERT';
+FraimLocalMCPServer.SESSION_HEADER = 'x-fraim-session-id';
+// Start server if run directly
+if (require.main === module) {
+    const server = new FraimLocalMCPServer();
+    server.start();
+}