fraim-framework 2.0.74 → 2.0.76

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

@@ -7,10 +7,10 @@
  * 1. Accepts MCP requests via stdin/stdout
  * 2. Proxies to remote FRAIM server
  * 3. Performs template substitution:
- *    - Config variables: {{config.path.to.value}}
- *    - Platform-specific actions: {{get_issue}}, {{create_pr}}, etc.
+ *    - 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 {{delivery.*}} templates based on user's workingStyle
+ * 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.
  */
@@ -35,39 +35,59 @@ class FraimTemplateEngine {
     constructor(opts) {
         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;
+    }
+    setConfig(config) {
+        this.config = config;
+    }
     substituteTemplates(content) {
         let result = content;
-        // First, substitute config variables with fallback support
-        if (this.config) {
-            result = result.replace(/\{\{config\.([^}|]+)(?:\s*\|\s*"([^"]+)")?\}\}/g, (match, path, fallback) => {
-                try {
+        // 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);
                     }
-                    if (fallback !== undefined) {
-                        return fallback;
-                    }
-                    return match;
                 }
-                catch (error) {
-                    return fallback !== undefined ? fallback : match;
-                }
-            });
-        }
-        // Second, substitute {{delivery.*}} templates
+                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(/\{\{delivery\.([^}]+)\}\}/g, (match, key) => {
-                const value = deliveryValues[`delivery.${key.trim()}`];
+            result = result.replace(/\{\{proxy\.delivery\.([^}]+)\}\}/g, (match, key) => {
+                const value = deliveryValues[`proxy.delivery.${key.trim()}`];
                 return value !== undefined ? value : match;
             });
         }
@@ -78,44 +98,12 @@ class FraimTemplateEngine {
     loadDeliveryTemplates() {
         if (this.deliveryTemplatesCache)
             return this.deliveryTemplatesCache;
-        const filename = this.workingStyle === 'Conversation' ? 'delivery-conversation.json' : 'delivery-pr.json';
-        try {
-            let content = null;
-            // Try framework installation directory first (relative to this file)
-            // This file is in dist/src/local-mcp-server/, so go up to framework root
-            const frameworkRoot = (0, path_1.join)(__dirname, '..', '..', '..');
-            const frameworkPath = (0, path_1.join)(frameworkRoot, 'registry', 'providers', filename);
-            if ((0, fs_1.existsSync)(frameworkPath)) {
-                content = (0, fs_1.readFileSync)(frameworkPath, 'utf-8');
-                this.logFn(`✅ Loaded delivery templates from framework: ${frameworkPath}`);
-            }
-            // Fallback: try node_modules if not found in framework root
-            if (!content) {
-                const nodeModulesPath = (0, path_1.join)(process.cwd(), 'node_modules', '@fraim', 'framework', 'registry', 'providers', filename);
-                if ((0, fs_1.existsSync)(nodeModulesPath)) {
-                    content = (0, fs_1.readFileSync)(nodeModulesPath, 'utf-8');
-                    this.logFn(`✅ Loaded delivery templates from node_modules: ${nodeModulesPath}`);
-                }
-            }
-            // Last resort: try project root (for custom overrides)
-            if (!content && this.projectRoot) {
-                const deliveryPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', filename);
-                if ((0, fs_1.existsSync)(deliveryPath)) {
-                    content = (0, fs_1.readFileSync)(deliveryPath, 'utf-8');
-                    this.logFn(`✅ Loaded delivery templates from project: ${deliveryPath}`);
-                }
-            }
-            if (content) {
-                this.deliveryTemplatesCache = JSON.parse(content);
-                return this.deliveryTemplatesCache;
-            }
-            this.logFn(`⚠️ Could not find delivery templates: ${filename}`);
+        if (this.deliveryTemplatesLoadAttempted)
             return null;
-        }
-        catch (error) {
-            this.logFn(`⚠️ Failed to load delivery templates: ${error.message}`);
-            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 provider = (0, provider_utils_1.detectProvider)(this.repoInfo?.url);
@@ -124,7 +112,8 @@ class FraimTemplateEngine {
             return content;
         let result = content;
         for (const [action, template] of Object.entries(templates)) {
-            const regex = new RegExp(`\\{\\{${action}\\}\\}`, 'g');
+            const escapedAction = action.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+            const regex = new RegExp(`\\{\\{${FraimTemplateEngine.PROXY_ACTION_PREFIX}${escapedAction}\\}\\}`, 'g');
             const renderedTemplate = this.renderActionTemplate(template);
             result = result.replace(regex, renderedTemplate);
         }
@@ -133,39 +122,12 @@ class FraimTemplateEngine {
     loadProviderTemplates(provider) {
         if (this.providerTemplatesCache[provider])
             return this.providerTemplatesCache[provider];
-        try {
-            let content = null;
-            // Try framework installation directory first (relative to this file)
-            const frameworkRoot = (0, path_1.join)(__dirname, '..', '..', '..');
-            const frameworkPath = (0, path_1.join)(frameworkRoot, 'registry', 'providers', `${provider}.json`);
-            if ((0, fs_1.existsSync)(frameworkPath)) {
-                content = (0, fs_1.readFileSync)(frameworkPath, 'utf-8');
-            }
-            // Fallback: try node_modules
-            if (!content) {
-                const nodeModulesPath = (0, path_1.join)(process.cwd(), 'node_modules', '@fraim', 'framework', 'registry', 'providers', `${provider}.json`);
-                if ((0, fs_1.existsSync)(nodeModulesPath)) {
-                    content = (0, fs_1.readFileSync)(nodeModulesPath, 'utf-8');
-                }
-            }
-            // Last resort: try project root (for custom overrides)
-            if (!content && this.projectRoot) {
-                const providerPath = (0, path_1.join)(this.projectRoot, 'registry', 'providers', `${provider}.json`);
-                if ((0, fs_1.existsSync)(providerPath)) {
-                    content = (0, fs_1.readFileSync)(providerPath, 'utf-8');
-                }
-            }
-            if (content) {
-                const templates = JSON.parse(content);
-                this.providerTemplatesCache[provider] = templates;
-                return templates;
-            }
-            return null;
-        }
-        catch (error) {
-            this.logFn(`⚠️ Failed to load provider templates: ${error.message}`);
+        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) {
@@ -173,8 +135,8 @@ class FraimTemplateEngine {
         }
         return template.replace(/\{\{([^}]+)\}\}/g, (match, path) => {
             const trimmedPath = path.trim();
-            if (trimmedPath.startsWith('repository.')) {
-                const repoPath = trimmedPath.substring('repository.'.length);
+            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)
@@ -191,6 +153,7 @@ class FraimTemplateEngine {
     }
 }
 exports.FraimTemplateEngine = FraimTemplateEngine;
+FraimTemplateEngine.PROXY_ACTION_PREFIX = 'proxy.action.';
 class FraimLocalMCPServer {
     constructor() {
         this.config = null;
@@ -200,7 +163,14 @@ class FraimLocalMCPServer {
         this.machineInfo = null;
         this.repoInfo = null;
         this.engine = null;
-        this.registryResolver = null;
+        this.fallbackRewriteCount = 0;
+        this.fallbackRewriteRequestCount = 0;
+        this.fallbackRewriteTokens = new Map();
+        this.pendingFallbackRequestCount = 0;
+        this.pendingFallbackTokenRewriteCount = 0;
+        this.pendingFallbackTokenCounts = new Map();
+        this.pendingFallbackEvents = [];
+        this.fallbackSummaryEmitted = false;
         this.remoteUrl = process.env.FRAIM_REMOTE_URL || 'https://fraim.wellnessatwork.me';
         this.apiKey = process.env.FRAIM_API_KEY || '';
         this.localVersion = this.detectLocalVersion();
@@ -331,12 +301,19 @@ class FraimLocalMCPServer {
                 this.log('✅ Loaded local .fraim/config.json');
             }
             else {
+                this.config = null;
                 this.log('⚠️ No .fraim/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);
+            }
         }
     }
     /**
@@ -479,91 +456,340 @@ class FraimLocalMCPServer {
         }
         return 'PR';
     }
-    substituteTemplates(content) {
+    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: this.detectRepoInfo(),
+                repoInfo,
                 workingStyle: this.getWorkingStyle(),
                 projectRoot: this.findProjectRoot(),
                 logFn: (msg) => this.log(msg)
             });
         }
-        return this.engine.substituteTemplates(content);
+        else {
+            this.engine.setConfig(this.config);
+            if (this.repoInfo) {
+                this.engine.setRepoInfo(this.repoInfo);
+            }
+        }
+        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 }
+            }
+        };
+        this.applyRequestSessionId(request, requestSessionId);
+        const response = await this.proxyToRemote(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 provider = (0, provider_utils_1.detectProvider)(this.detectRepoInfo()?.url);
+        if (engine.hasProviderTemplates(provider))
+            return;
+        if (engine.loadProviderTemplates(provider))
+            return;
+        const filename = `${provider}.json`;
+        const cached = this.readCachedTemplateFile(filename);
+        if (cached) {
+            engine.setProviderTemplates(provider, cached);
+            return;
+        }
+        const remoteContent = await this.fetchRegistryFileFromServer(`providers/${filename}`, requestSessionId);
+        if (!remoteContent)
+            return;
+        const parsed = this.parseTemplateJson(remoteContent, `providers/${filename}`);
+        if (!parsed)
+            return;
+        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 provider = (0, provider_utils_1.detectProvider)(this.detectRepoInfo()?.url);
+        const engine = this.ensureEngine();
+        if (this.responseHasPotentialProviderPlaceholders(processedResponse) &&
+            !engine.hasProviderTemplates(provider)) {
+            await this.ensureProviderTemplatesAvailable(processedResponse, requestSessionId);
+            processedResponse = this.processResponse(processedResponse);
+        }
+        return this.applyAgentFallbackForUnresolvedProxy(processedResponse);
+    }
+    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() {
-        if (!this.registryResolver) {
-            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
-                this.registryResolver = new local_registry_resolver_1.LocalRegistryResolver({
-                    workspaceRoot: process.cwd(),
-                    remoteContentResolver: async (path) => {
-                        throw new Error('No project root available');
+    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');
+                }
+            });
+        }
+        else {
+            return new local_registry_resolver_1.LocalRegistryResolver({
+                workspaceRoot: projectRoot,
+                remoteContentResolver: async (path) => {
+                    // Fetch parent content from remote for inheritance
+                    this.log(`🔄 Remote content resolver: fetching ${path}`);
+                    let request;
+                    if (path.startsWith('workflows/')) {
+                        // Extract workflow name from path: workflows/category/name.md -> name
+                        const pathParts = path.replace('workflows/', '').replace('.md', '').split('/');
+                        const workflowName = pathParts[pathParts.length - 1]; // Get last part (name)
+                        this.log(`🔄 Fetching workflow: ${workflowName}`);
+                        request = {
+                            jsonrpc: '2.0',
+                            id: (0, crypto_1.randomUUID)(),
+                            method: 'tools/call',
+                            params: {
+                                name: 'get_fraim_workflow',
+                                arguments: { workflow: workflowName }
+                            }
+                        };
                     }
-                });
-            }
-            else {
-                this.registryResolver = new local_registry_resolver_1.LocalRegistryResolver({
-                    workspaceRoot: projectRoot,
-                    remoteContentResolver: async (path) => {
-                        // Fetch parent content from remote for inheritance
-                        this.log(`🔄 Remote content resolver: fetching ${path}`);
-                        let request;
-                        if (path.startsWith('workflows/')) {
-                            // Extract workflow name from path: workflows/category/name.md -> name
-                            const pathParts = path.replace('workflows/', '').replace('.md', '').split('/');
-                            const workflowName = pathParts[pathParts.length - 1]; // Get last part (name)
-                            this.log(`🔄 Fetching workflow: ${workflowName}`);
-                            request = {
-                                jsonrpc: '2.0',
-                                id: (0, crypto_1.randomUUID)(),
-                                method: 'tools/call',
-                                params: {
-                                    name: 'get_fraim_workflow',
-                                    arguments: { workflow: workflowName }
-                                }
-                            };
-                        }
-                        else {
-                            // For non-workflow files (templates, rules, etc.), use get_fraim_file
-                            this.log(`🔄 Fetching file: ${path}`);
-                            request = {
-                                jsonrpc: '2.0',
-                                id: (0, crypto_1.randomUUID)(),
-                                method: 'tools/call',
-                                params: {
-                                    name: 'get_fraim_file',
-                                    arguments: { path }
-                                }
-                            };
-                        }
-                        const response = await this.proxyToRemote(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;
+                    else {
+                        // For non-workflow files (templates, rules, etc.), use get_fraim_file
+                        this.log(`🔄 Fetching file: ${path}`);
+                        request = {
+                            jsonrpc: '2.0',
+                            id: (0, crypto_1.randomUUID)(),
+                            method: 'tools/call',
+                            params: {
+                                name: 'get_fraim_file',
+                                arguments: { path }
                             }
+                        };
+                    }
+                    this.applyRequestSessionId(request, requestSessionId);
+                    const response = await this.proxyToRemote(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}`);
                     }
-                });
-            }
+                    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}`);
+                }
+            });
         }
-        return this.registryResolver;
     }
     /**
      * Determine workflow category from workflow name
@@ -625,11 +851,121 @@ class FraimLocalMCPServer {
             result: processValue(response.result)
         };
     }
+    applyAgentFallbackForUnresolvedProxy(response) {
+        if (!response.result)
+            return response;
+        const rewritten = this.rewriteUnresolvedProxyPlaceholders(response.result);
+        if (rewritten.tokens.length > 0) {
+            this.recordFallbackRewrite(rewritten.tokens);
+            this.logError(`[${FraimLocalMCPServer.FALLBACK_ALERT_MARKER}] Rewrote unresolved proxy placeholders to agent placeholders: ${rewritten.tokens.join(', ')}`);
+        }
+        return {
+            ...response,
+            result: rewritten.value
+        };
+    }
+    recordFallbackRewrite(tokens) {
+        this.fallbackRewriteRequestCount += 1;
+        this.fallbackRewriteCount += tokens.length;
+        for (const token of tokens) {
+            const existing = this.fallbackRewriteTokens.get(token) || 0;
+            this.fallbackRewriteTokens.set(token, existing + 1);
+        }
+        this.pendingFallbackRequestCount += 1;
+        this.pendingFallbackTokenRewriteCount += tokens.length;
+        for (const token of tokens) {
+            const existing = this.pendingFallbackTokenCounts.get(token) || 0;
+            this.pendingFallbackTokenCounts.set(token, existing + 1);
+        }
+        this.pendingFallbackEvents.push({
+            at: new Date().toISOString(),
+            tokenCount: tokens.length,
+            tokens: [...tokens]
+        });
+        if (this.pendingFallbackEvents.length > 250) {
+            this.pendingFallbackEvents = this.pendingFallbackEvents.slice(-250);
+        }
+    }
+    buildPendingFallbackTelemetryPayload() {
+        if (this.pendingFallbackRequestCount === 0 &&
+            this.pendingFallbackTokenRewriteCount === 0 &&
+            this.pendingFallbackEvents.length === 0) {
+            return null;
+        }
+        const tokenCounts = {};
+        for (const [token, count] of this.pendingFallbackTokenCounts.entries()) {
+            tokenCounts[token] = count;
+        }
+        return {
+            requestFallbacks: this.pendingFallbackRequestCount,
+            tokenRewrites: this.pendingFallbackTokenRewriteCount,
+            tokenCounts,
+            events: this.pendingFallbackEvents.map((event) => ({
+                at: event.at,
+                tokenCount: event.tokenCount,
+                tokens: [...event.tokens]
+            }))
+        };
+    }
+    acknowledgePendingFallbackTelemetry(payload) {
+        this.pendingFallbackRequestCount = Math.max(0, this.pendingFallbackRequestCount - payload.requestFallbacks);
+        this.pendingFallbackTokenRewriteCount = Math.max(0, this.pendingFallbackTokenRewriteCount - payload.tokenRewrites);
+        for (const [token, sentCount] of Object.entries(payload.tokenCounts)) {
+            const current = this.pendingFallbackTokenCounts.get(token) || 0;
+            const next = Math.max(0, current - Math.max(0, sentCount));
+            if (next === 0) {
+                this.pendingFallbackTokenCounts.delete(token);
+            }
+            else {
+                this.pendingFallbackTokenCounts.set(token, next);
+            }
+        }
+        if (payload.events.length > 0) {
+            this.pendingFallbackEvents.splice(0, Math.min(payload.events.length, this.pendingFallbackEvents.length));
+        }
+    }
+    emitFallbackSummary(reason) {
+        if (this.fallbackSummaryEmitted)
+            return;
+        this.fallbackSummaryEmitted = true;
+        if (this.fallbackRewriteCount === 0)
+            return;
+        const topTokens = Array.from(this.fallbackRewriteTokens.entries())
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([token, count]) => `${token}:${count}`)
+            .join(', ');
+        this.logError(`[${FraimLocalMCPServer.FALLBACK_SUMMARY_MARKER}] reason=${reason} requestFallbacks=${this.fallbackRewriteRequestCount} tokenRewrites=${this.fallbackRewriteCount} uniqueTokens=${this.fallbackRewriteTokens.size}${topTokens ? ` topTokens=${topTokens}` : ''}`);
+    }
+    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;
+        }
+    }
     /**
      * Proxy request to remote FRAIM server
      */
     async proxyToRemote(request) {
         const requestId = (0, crypto_1.randomUUID)();
+        let sentFallbackTelemetry = null;
         try {
             // Special handling for fraim_connect - automatically inject machine and repo info
             if (request.method === 'tools/call' && request.params?.name === 'fraim_connect') {
@@ -670,19 +1006,38 @@ class FraimLocalMCPServer {
                     }
                     this.log(`[req:${requestId}] Using agent-provided repo info: ${args.repo.owner}/${args.repo.name}`);
                 }
+                // Keep proxy runtime repository context in sync with connect payload.
+                this.repoInfo = args.repo;
+                if (this.engine) {
+                    this.engine.setRepoInfo(args.repo);
+                }
                 // Update the request with injected info
                 request.params.arguments = args;
             }
+            sentFallbackTelemetry = this.buildPendingFallbackTelemetryPayload();
+            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;
+            }
+            if (sentFallbackTelemetry) {
+                headers[FraimLocalMCPServer.FALLBACK_HEADER] = Buffer
+                    .from(JSON.stringify(sentFallbackTelemetry), 'utf8')
+                    .toString('base64');
+            }
             this.log(`[req:${requestId}] Proxying ${request.method} to ${this.remoteUrl}/mcp`);
             const response = await axios_1.default.post(`${this.remoteUrl}/mcp`, request, {
-                headers: {
-                    'Content-Type': 'application/json',
-                    'x-api-key': this.apiKey,
-                    'x-fraim-request-id': requestId,
-                    'x-fraim-local-version': this.localVersion
-                },
+                headers,
                 timeout: 30000
             });
+            if (sentFallbackTelemetry) {
+                this.acknowledgePendingFallbackTelemetry(sentFallbackTelemetry);
+            }
             return response.data;
         }
         catch (error) {
@@ -707,6 +1062,10 @@ class FraimLocalMCPServer {
                         localMcpVersion: this.localVersion
                     };
                 }
+                if (sentFallbackTelemetry) {
+                    // Request reached the server and produced a response; clear sent fallback delta.
+                    this.acknowledgePendingFallbackTelemetry(sentFallbackTelemetry);
+                }
                 return forwarded;
             }
             return {
@@ -757,6 +1116,7 @@ class FraimLocalMCPServer {
      */
     async handleRequest(request) {
         this.log(`📥 ${request.method}`);
+        const requestSessionId = this.extractSessionIdFromRequest(request);
         // Special handling for initialize request
         if (request.method === 'initialize') {
             // Check if client supports roots
@@ -767,12 +1127,15 @@ class FraimLocalMCPServer {
             }
             // Proxy initialize to remote server first
             const response = await this.proxyToRemote(request);
-            const processedResponse = this.processResponse(response);
+            const processedResponse = await this.processResponseWithHydration(response, requestSessionId);
             // After successful initialization, load config
             if (!processedResponse.error) {
-                // For now, don't request roots - just use env var + upward search
-                // TODO: Implement roots/list properly after initialization is complete
+                // 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;
@@ -797,7 +1160,7 @@ class FraimLocalMCPServer {
                         const category = this.getWorkflowCategory(workflowName);
                         requestedPath = `workflows/${category}/${workflowName}.md`;
                         this.log(`🔍 Checking for override: ${requestedPath}`);
-                        const resolver = this.getRegistryResolver();
+                        const resolver = this.getRegistryResolver(requestSessionId);
                         const hasOverride = resolver.hasLocalOverride(requestedPath);
                         this.log(`🔍 hasLocalOverride(${requestedPath}) = ${hasOverride}`);
                         if (hasOverride) {
@@ -818,7 +1181,7 @@ class FraimLocalMCPServer {
                                 }
                             };
                             // Apply template substitution
-                            const processedResponse = this.processResponse(response);
+                            const processedResponse = await this.processResponseWithHydration(response, requestSessionId);
                             this.log(`📤 ${request.method} → OK`);
                             return processedResponse;
                         }
@@ -830,31 +1193,37 @@ class FraimLocalMCPServer {
                         this.log('⚠️ No path provided in get_fraim_file');
                     }
                     else {
-                        this.log(`🔍 Checking for override: ${requestedPath}`);
-                        const resolver = this.getRegistryResolver();
-                        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 = this.processResponse(response);
-                            this.log(`📤 ${request.method} → OK`);
-                            return processedResponse;
+                        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 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.processResponseWithHydration(response, requestSessionId);
+                                this.log(`📤 ${request.method} → OK`);
+                                return processedResponse;
+                            }
                         }
                     }
                 }
@@ -867,8 +1236,7 @@ class FraimLocalMCPServer {
         }
         // Proxy to remote server
         const response = await this.proxyToRemote(request);
-        // Process template substitution (config vars, platform actions, delivery templates)
-        const processedResponse = this.processResponse(response);
+        const processedResponse = await this.processResponseWithHydration(response, requestSessionId);
         this.log(`📤 ${request.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
         return processedResponse;
     }
@@ -891,11 +1259,12 @@ class FraimLocalMCPServer {
                     // Use the first root (typically the primary workspace folder)
                     const firstRoot = roots[0];
                     if (firstRoot.uri && firstRoot.uri.startsWith('file://')) {
-                        // Convert file:// URI to local path
-                        // Handle both Unix (/path) and Windows (C:/path) paths
-                        let rootPath = firstRoot.uri.replace('file://', '');
-                        // Windows: file:///C:/path -> C:/path
-                        rootPath = rootPath.replace(/^\/([A-Z]:)/i, '$1');
+                        const rootPath = this.fileUriToLocalPath(firstRoot.uri);
+                        if (!rootPath) {
+                            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
@@ -913,6 +1282,47 @@ class FraimLocalMCPServer {
             }
         }
     }
+    /**
+     * 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
      */
@@ -974,20 +1384,31 @@ class FraimLocalMCPServer {
         });
         process.stdin.on('end', () => {
             this.log('🛑 Stdin closed, shutting down...');
+            this.emitFallbackSummary('stdin_end');
             process.exit(0);
         });
         process.on('SIGTERM', () => {
             this.log('🛑 SIGTERM received, shutting down...');
+            this.emitFallbackSummary('sigterm');
             process.exit(0);
         });
         process.on('SIGINT', () => {
             this.log('🛑 SIGINT received, shutting down...');
+            this.emitFallbackSummary('sigint');
             process.exit(0);
         });
         this.log('✅ FRAIM Local MCP Server ready');
     }
 }
 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.FALLBACK_SUMMARY_MARKER = 'PROXY_FALLBACK_SUMMARY';
+FraimLocalMCPServer.FALLBACK_HEADER = 'x-fraim-proxy-fallback-telemetry';
+FraimLocalMCPServer.SESSION_HEADER = 'x-fraim-session-id';
 // Start server if run directly
 if (require.main === module) {
     const server = new FraimLocalMCPServer();