fraim 2.0.179 → 2.0.182

package/dist/src/services/mcp-service.js

@@ -0,0 +1,823 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.McpService = exports.REQUIRED_QUALITY_FIELDS = exports.QUALITY_SCORE_JOBS = exports.QUALITY_PRODUCING_JOBS = exports.DEFAULT_LAUNCH_PHRASE_MAPPINGS = void 0;
+const fs_1 = require("fs");
+const crypto_1 = require("crypto");
+const job_parser_1 = require("../core/utils/job-parser");
+const provider_utils_1 = require("../core/utils/provider-utils");
+const issues_1 = require("../fraim/issues");
+const tool_schemas_1 = require("../mcp/tool-schemas");
+const semver = __importStar(require("semver"));
+const compat_1 = require("../config/compat");
+const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
+const quality_evidence_1 = require("../core/quality-evidence");
+const feature_flags_1 = require("../config/feature-flags");
+const persona_entitlement_service_1 = require("./persona-entitlement-service");
+const FRAIM_PROMPT_TEXT = `You are running in FRAIM mode. Follow this process:
+
+0. **Preload deferred FRAIM tools when needed**: If FRAIM MCP tools are unavailable because this host lazily loads deferred tool schemas, call ToolSearch once to load fraim_connect, list_fraim_jobs, get_fraim_job, get_fraim_file, seekMentoring. Do the preload as one batched discovery step, not one search per tool.
+
+1. **If the user did not specify a FRAIM job or topic**: If local FRAIM job stubs are present in the workspace, inspect those first and match the request locally. Also inspect fraim/personalized-employee/jobs/ for local overrides or repo-specific jobs. If local files are missing or you cannot inspect workspace files, call list_fraim_jobs() to view the full catalog, including any proxy-discoverable personalized jobs.
+
+2. **Find the match**: Match the user's request to a FRAIM job from the local stub catalog, fraim/personalized-employee/jobs/, or the full list_fraim_jobs() response. If no job matches, try a likely FRAIM skill with get_fraim_file({ path: "skills/<likely-category>/<argument>.md" }) and confirm the match with the user.
+
+3. **Load the full content**:
+   - For jobs, call get_fraim_job({ job: "<matched-job-name>" }).
+   - For skills, use the content returned by get_fraim_file(...).
+
+4. **Execute**:
+   - For jobs, follow the phased instructions and use seekMentoring when the job requires phase transitions.
+   - For skills, apply the skill steps directly to the user's current context.`;
+exports.DEFAULT_LAUNCH_PHRASE_MAPPINGS = {
+    'Onboard this project': 'get_fraim_job({ job: "project-onboarding" })',
+    'sleep on learnings': 'get_fraim_job({ job: "sleep-on-learnings" })',
+    'Personalize my employee': 'get_fraim_job({ job: "evolve-employee" })',
+    'Evolve my employee': 'get_fraim_job({ job: "evolve-employee" })'
+};
+/**
+ * Re-export quality evidence contract from src/core/quality-evidence.
+ * Kept here for backward compatibility with existing imports from
+ * tests/test-quality-scores.ts and other services.
+ */
+exports.QUALITY_PRODUCING_JOBS = quality_evidence_1.QUALITY_PRODUCING_JOBS;
+exports.QUALITY_SCORE_JOBS = quality_evidence_1.QUALITY_SCORE_JOBS;
+exports.REQUIRED_QUALITY_FIELDS = quality_evidence_1.REQUIRED_QUALITY_FIELDS;
+class McpService {
+    constructor(registryService, sessionManager, aiMentor, dbService, analyticsServiceOrVersion, serverVersion) {
+        this.registryService = registryService;
+        this.sessionManager = sessionManager;
+        this.aiMentor = aiMentor;
+        this.dbService = dbService;
+        // Support both old 5-arg and new 6-arg signatures
+        if (typeof analyticsServiceOrVersion === 'string') {
+            this.serverVersion = analyticsServiceOrVersion;
+        }
+        else {
+            this.analyticsService = analyticsServiceOrVersion;
+            this.serverVersion = serverVersion;
+        }
+    }
+    getProjectRulesPath() {
+        return (0, project_fraim_paths_1.getWorkspaceFraimPath)(process.env.FRAIM_WORKSPACE_ROOT || process.cwd(), 'personalized-employee', 'rules', 'project_rules.md');
+    }
+    buildDiscoveryResponse(matches) {
+        const lines = ['# Available FRAIM Jobs'];
+        lines.push('', 'Showing the full FRAIM job catalog.');
+        const categorized = {};
+        for (const match of matches) {
+            if (!categorized[match.category]) {
+                categorized[match.category] = [];
+            }
+            categorized[match.category].push(match);
+        }
+        for (const [category, jobList] of Object.entries(categorized)) {
+            lines.push('', `## ${category}`);
+            for (const job of jobList) {
+                lines.push(`- **${job.name}**: ${job.description}`);
+            }
+        }
+        lines.push('', '## Next Step', 'Call `get_fraim_job({ job: "<name>" })` for the best match, then use `seekMentoring` for phase progression.');
+        return lines.join('\n');
+    }
+    /**
+     * Handle incoming MCP requests
+     */
+    async handleRequest(reqBody, context) {
+        const { method, params, id } = reqBody;
+        try {
+            let result;
+            if (method === 'initialize') {
+                result = this.handleInitialize();
+            }
+            else if (method === 'tools/list') {
+                result = this.handleListTools(context);
+            }
+            else if (method === 'resources/list') {
+                result = this.handleListResources();
+            }
+            else if (method === 'prompts/list') {
+                result = this.handleListPrompts();
+            }
+            else if (method === 'prompts/get') {
+                result = this.handleGetPrompt(params);
+            }
+            else if (method === 'tools/call') {
+                result = await this.handleToolCall(params, context);
+            }
+            else if (method === 'notifications/initialized') {
+                // Notifications don't need a response
+                return null;
+            }
+            else {
+                throw new Error(`Method not found: ${method}`);
+            }
+            return result;
+        }
+        catch (error) {
+            console.error(`[req:${context.requestId}] MCP service error:`, error);
+            throw error;
+        }
+    }
+    handleInitialize() {
+        return {
+            protocolVersion: '2024-11-05',
+            serverInfo: {
+                name: 'fraim-mcp-server',
+                version: this.serverVersion
+            },
+            capabilities: {
+                tools: {},
+                resources: {},
+                prompts: {}
+            }
+        };
+    }
+    handleListTools(context) {
+        const surface = !context
+            ? 'local-proxy'
+            : context.localMcpVersion && context.localMcpVersion !== 'unknown'
+                ? 'local-proxy'
+                : 'remote';
+        return {
+            tools: (0, tool_schemas_1.getToolDefinitions)(this.getAvailableJobs(), { surface })
+        };
+    }
+    handleListResources() {
+        return { resources: [] };
+    }
+    handleListPrompts() {
+        return {
+            prompts: [
+                {
+                    name: 'fraim',
+                    description: 'Activate a FRAIM job or skill. Scans the job catalog, matches your request, loads full phased instructions, and executes.',
+                    arguments: [
+                        {
+                            name: 'task',
+                            description: 'Job, skill, or task to run (e.g. "feature-specification", "sleep on learnings"). Omit to let FRAIM match from context.',
+                            required: false
+                        }
+                    ]
+                }
+            ]
+        };
+    }
+    handleGetPrompt(params) {
+        const { name, arguments: promptArgs } = params ?? {};
+        if (name !== 'fraim') {
+            const err = new Error(`Prompt not found: ${name}`);
+            err.code = -32602;
+            throw err;
+        }
+        const task = promptArgs?.task ? String(promptArgs.task) : '';
+        const taskSuffix = task ? `\n\nTask: ${task}` : '';
+        return {
+            description: 'Activate a FRAIM job or skill',
+            messages: [
+                {
+                    role: 'user',
+                    content: {
+                        type: 'text',
+                        text: FRAIM_PROMPT_TEXT + taskSuffix
+                    }
+                }
+            ]
+        };
+    }
+    async handleToolCall(params, context) {
+        let result = await this.handleToolCallInternal(params, context);
+        // Inject migration notice for old clients
+        if (context.localMcpVersion && context.localMcpVersion !== 'unknown') {
+            try {
+                // Check for breaking changes/minimum version
+                const isOutdated = semver.valid(context.localMcpVersion) &&
+                    semver.lt(context.localMcpVersion, compat_1.MINIMUM_CLIENT_VERSION);
+                if (isOutdated && result && Array.isArray(result.content)) {
+                    // Avoid duplicating the notice if somehow we recursively called
+                    const hasNotice = result.content.some((c) => c.text && c.text.includes('migration_notice'));
+                    if (!hasNotice) {
+                        result.content.push({
+                            type: 'text',
+                            text: (0, compat_1.getBreakingChangesNotice)(context.localMcpVersion)
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                // Ignore semver errors
+            }
+        }
+        return result;
+    }
+    async handleToolCallInternal(params, context) {
+        const { name: toolName, arguments: toolArgs } = params;
+        if (!toolName)
+            throw new Error('Tool name is required');
+        const args = toolArgs || {};
+        switch (toolName) {
+            case 'get_fraim_file':
+                if (!args.path)
+                    throw new Error('Argument "path" is required for get_fraim_file');
+                return await this.handleGetFile(args.path, { raw: args.raw });
+            case 'get_fraim_job':
+                if (!args.job)
+                    throw new Error('Argument "job" is required for get_fraim_job');
+                return await this.handleGetJob(args.job, context.apiKey, context.userId);
+            case 'seekMentoring':
+                if (!args.jobName || !args.issueNumber || !args.currentPhase || !args.status || !args.jobId) {
+                    throw new Error('Arguments "jobName", "jobId", "issueNumber", "currentPhase", and "status" are required for seekMentoring');
+                }
+                return await this.handleSeekMentoring(args, context.userId);
+            case 'list_fraim_jobs':
+                return await this.handleListJobs();
+            case 'file_fraim_github_issue':
+            case 'file_issue': // Backward compatibility alias
+                if (!args.title || !args.body)
+                    throw new Error('Arguments "title" and "body" are required for file_fraim_github_issue');
+                const result = await (0, issues_1.fileFraimIssue)({ ...args, reporterEmail: context.userId });
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(result, null, 2)
+                        }]
+                };
+            case 'list_my_fraim_github_issues':
+                const listResult = await (0, issues_1.listFraimIssuesByReporter)({
+                    reporterEmail: context.userId,
+                    limit: args.limit
+                });
+                return {
+                    content: [{
+                            type: 'text',
+                            text: JSON.stringify(listResult, null, 2)
+                        }]
+                };
+            case 'fraim_connect':
+                return await this.handleFraimConnect(args, context.apiKey, context.userId, context);
+            default:
+                throw new Error(`Unknown tool: ${toolName} `);
+        }
+    }
+    async handleGetFile(path, options = {}) {
+        const metadata = this.registryService.findFileByPath(path);
+        const isRaw = options.raw === true;
+        if (!metadata) {
+            throw new Error(`File not found: ${path}. Check for typos in the file name or file path.`);
+        }
+        if (!isRaw && metadata.type === 'job') {
+            throw new Error(`Jobs cannot be retrieved via get_fraim_file. Use get_fraim_job({ job: "${metadata.name.replace('.md', '')}" }) instead.`);
+        }
+        try {
+            let content = (0, fs_1.readFileSync)(metadata.fullPath, 'utf8');
+            if (isRaw) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: content
+                        }]
+                };
+            }
+            const hasProxyTemplateVars = /\{\{proxy\.[^}]+\}\}/.test(content);
+            const hasAgentTemplateVars = /\{\{agent\.[^}]+\}\}/.test(content);
+            let header = `# ${metadata.name} \n\n`;
+            header += `** Path:** ${path} \n`;
+            header += `** Type:** ${metadata.type} \n`;
+            if (metadata.category) {
+                header += `** Category:** ${metadata.category} \n`;
+            }
+            if (hasProxyTemplateVars) {
+                header += `\n## Proxy Variables\n\n`;
+                header += `This file contains placeholders like \`{{proxy.config.project.name}}\`.\n\n`;
+                header += `These are resolved deterministically by the local FRAIM proxy and should not be manually replaced by the agent.\n\n`;
+            }
+            if (hasAgentTemplateVars) {
+                header += `\n## Agent Variables Detected\n\n`;
+                header += `This file contains placeholders like \`{{agent.issue_number}}\`.\n\n`;
+                header += `These must be filled by the agent/runtime from the active task context.\n\n`;
+            }
+            if (metadata.type === 'script') {
+                header += `\n## 🛡️ Ephemeral Execution Mandatory (IP Protection)\n\n`;
+                header += `This script MUST be executed ephemerally (see rules/ephemeral-execution.md).\n\n`;
+            }
+            header += `---\n\n`;
+            return {
+                content: [{
+                        type: 'text',
+                        text: header + content
+                    }]
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to read file: ${error.message}`);
+        }
+    }
+    async handleGetJob(jobName, apiKey, userId) {
+        let effectiveUserId = userId;
+        if (!effectiveUserId && apiKey) {
+            try {
+                const apiKeyData = await this.dbService.getApiKeyByKey(apiKey);
+                effectiveUserId = apiKeyData?.userId;
+            }
+            catch (e) {
+                console.error(`❌ McpService: API key lookup error:`, e);
+            }
+        }
+        const personaLock = await this.maybeBuildPersonaLockResponse(jobName, effectiveUserId, apiKey, false);
+        if (personaLock) {
+            return personaLock;
+        }
+        const result = await this.aiMentor.getJobOverview(jobName);
+        if (!result) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Job "${jobName}" not found.`
+                    }]
+            };
+        }
+        // Generate jobId for tracking
+        const jobId = (0, crypto_1.randomUUID)();
+        let sessionId = 'unknown';
+        // Get session info for tracking
+        if (apiKey) {
+            try {
+                const session = await this.dbService.getActiveSessionByApiKey(apiKey);
+                if (session) {
+                    sessionId = session.sessionId;
+                    userId = session.userId;
+                }
+            }
+            catch (e) {
+                console.error(`❌ McpService: Session lookup error:`, e);
+            }
+        }
+        // Create job execution record using usage events
+        if (userId && this.analyticsService) {
+            try {
+                await this.analyticsService.logJobStart(jobId, jobName, userId, sessionId);
+            }
+            catch (e) {
+                console.error(`❌ McpService: Failed to log job start:`, e);
+            }
+        }
+        let response = result.overview;
+        // Inject phase-authority for phased jobs
+        if (!result.isSimple) {
+            response = `${this.aiMentor.getCompactPhaseAuthority()}\n\n${response}`;
+        }
+        if (apiKey) {
+            try {
+                const session = await this.dbService.getActiveSessionByApiKey(apiKey);
+                if (session?.repo) {
+                    const provider = session.repo.provider || (0, provider_utils_1.detectProvider)(session.repo.url);
+                    const lines = response.split('\n');
+                    if (lines.length > 0) {
+                        lines.splice(1, 0, `\n**Platform:** ${provider.toUpperCase()}\n`);
+                        response = lines.join('\n');
+                    }
+                }
+                // Learning context is injected by the local proxy (learning-context-builder.ts),
+                // not by the server, because learning files live in the local workspace.
+            }
+            catch (e) {
+                console.error(`❌ McpService: Session lookup error:`, e);
+            }
+        }
+        if (!result.isSimple) {
+            response += `\n\n---\n\n**Job ID:** \`${jobId}\`\n\n**This job has phases.** Use \`seekMentoring\` with the jobId above to get phase-specific instructions.`;
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: response
+                }]
+        };
+    }
+    async handleListJobs() {
+        const jobs = Array.from(this.registryService.getFileIndex().values()).filter((f) => f.type === 'job' && !f.isStub);
+        const uniqueJobs = new Map();
+        for (const job of jobs) {
+            const jobName = job.name.replace('.md', '');
+            if (!uniqueJobs.has(jobName)) {
+                uniqueJobs.set(jobName, job);
+            }
+        }
+        const matches = [];
+        for (const job of uniqueJobs.values()) {
+            const category = job.category || 'Other';
+            const jobName = job.name.replace('.md', '');
+            const description = this.getJobDescription(jobName, job.fullPath);
+            matches.push({
+                name: jobName,
+                description,
+                category
+            });
+        }
+        matches.sort((a, b) => a.category.localeCompare(b.category) || a.name.localeCompare(b.name));
+        const response = this.buildDiscoveryResponse(matches);
+        return {
+            content: [{
+                    type: 'text',
+                    text: response
+                }]
+        };
+    }
+    async handleListFiles(type, category) {
+        let files = Array.from(this.registryService.getFileIndex().values());
+        if (type !== 'all') {
+            files = files.filter(f => f.type === type);
+        }
+        if (category) {
+            files = files.filter(f => f.category === category);
+        }
+        files.sort((a, b) => {
+            if (a.type !== b.type)
+                return a.type.localeCompare(b.type);
+            return a.path.localeCompare(b.path);
+        });
+        const filesList = files.map(f => {
+            return `- **${f.type}**${f.category ? ` (${f.category})` : ''}: \`${f.path}\``;
+        }).join('\n');
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# FRAIM Files\n\n**Total:** ${files.length} file(s)\n\n${filesList}`
+                }]
+        };
+    }
+    async handleFraimConnect(args, apiKey, userId, context) {
+        if (!apiKey)
+            throw new Error('No API Key found');
+        if (!args.agent?.name || !args.agent?.model) {
+            throw new Error('Agent information is required (name and model)');
+        }
+        const isLocalProxyCall = !!context?.localMcpVersion && context.localMcpVersion !== 'unknown';
+        const hasCompleteMachine = !!args.machine?.hostname &&
+            !!args.machine?.platform &&
+            typeof args.machine?.memory === 'number' &&
+            typeof args.machine?.cpus === 'number';
+        const hasRepoUrl = !!args.repo?.url;
+        if (isLocalProxyCall && (!args.machine?.hostname || !args.machine?.platform)) {
+            throw new Error('Machine hostname and platform are required');
+        }
+        if (isLocalProxyCall && (typeof args.machine?.memory !== 'number' || typeof args.machine?.cpus !== 'number')) {
+            throw new Error('Machine memory and cpus are required');
+        }
+        if (isLocalProxyCall && !args.repo?.url) {
+            throw new Error('Repository URL is required');
+        }
+        if (args.issueTracking) {
+            this.validateIssueTrackingConfig(args.issueTracking);
+        }
+        const finalMachineInfo = hasCompleteMachine
+            ? args.machine
+            : {
+                ...(args.machine || {}),
+                hostname: args.machine?.hostname || 'hosted-marketplace-client',
+                platform: args.machine?.platform || 'web',
+                memory: typeof args.machine?.memory === 'number' ? args.machine.memory : 0,
+                cpus: typeof args.machine?.cpus === 'number' ? args.machine.cpus : 0,
+                context: 'hosted-marketplace'
+            };
+        const finalRepoInput = hasRepoUrl
+            ? args.repo
+            : {
+                url: 'https://github.com/mathursrus/FRAIM',
+                owner: 'mathursrus',
+                name: 'FRAIM',
+                branch: 'master',
+                context: 'hosted-marketplace'
+            };
+        const provider = (0, provider_utils_1.detectProvider)(finalRepoInput.url);
+        const finalRepoInfo = { ...finalRepoInput, provider };
+        const finalIssueTracking = args.issueTracking ? this.normalizeIssueTrackingConfig(args.issueTracking) : undefined;
+        const sessionId = (0, crypto_1.randomUUID)();
+        const finalUserId = userId || 'unknown';
+        const session = {
+            sessionId,
+            userId: finalUserId,
+            agent: args.agent,
+            machine: finalMachineInfo,
+            repo: finalRepoInfo,
+            ...(finalIssueTracking ? { issueTracking: finalIssueTracking } : {}),
+            startTime: new Date(),
+            lastActive: new Date()
+        };
+        const keyData = await this.dbService.verifyApiKey(apiKey);
+        if (keyData)
+            session.userId = keyData.userId;
+        await this.dbService.createSession(session);
+        this.sessionManager.registerSession(apiKey, sessionId);
+        const projectRulesPath = (0, project_fraim_paths_1.getWorkspaceFraimDisplayPath)('personalized-employee/rules/project_rules.md');
+        const userEmail = session.userId !== 'unknown' ? session.userId : null;
+        const lines = [
+            `FRAIM session active. Session ID: ${sessionId}`,
+            '',
+            '## Start Here',
+            '- If local FRAIM job stubs are present under `fraim/ai-employee/jobs/` or `fraim/ai-manager/jobs/`, inspect those first to choose the best job.',
+            '- Also inspect `fraim/personalized-employee/jobs/` for local job overrides or repo-specific jobs.',
+            '- If the user already named a job, call `get_fraim_job({ job: "<job-name>" })`.',
+            '- If local stubs are missing or you cannot inspect workspace files, call `list_fraim_jobs()` to view the full catalog, then pick the best match yourself.',
+            '- Use `get_fraim_file(...)` only for the specific skills or rules needed for the current task.',
+            '- Once a phased job starts, use `seekMentoring` for phase-specific instructions and transitions.'
+        ];
+        if ((0, fs_1.existsSync)(this.getProjectRulesPath())) {
+            lines.push('', '## Required Project Rules', `Read \`${projectRulesPath}\` before doing work in this repo.`);
+        }
+        if (userEmail) {
+            lines.push('', '## Your Identity', '', `Your identity for this session: **${userEmail}**`);
+        }
+        // Learning context is injected by the local proxy (learning-context-builder.ts)
+        // after this response is received, because learning files live in the local workspace.
+        return {
+            content: [{
+                    type: 'text',
+                    text: lines.join('\n')
+                }],
+            sessionId: sessionId
+        };
+    }
+    validateIssueTrackingConfig(issueTracking) {
+        if (!issueTracking.provider) {
+            throw new Error('issueTracking.provider is required when issueTracking is provided');
+        }
+        if (issueTracking.provider === 'github') {
+            if (!issueTracking.owner || !issueTracking.name) {
+                throw new Error('GitHub issueTracking requires owner and name');
+            }
+            return;
+        }
+        if (issueTracking.provider === 'ado') {
+            if (!issueTracking.organization || !issueTracking.project || !issueTracking.name) {
+                throw new Error('ADO issueTracking requires organization, project, and name');
+            }
+            return;
+        }
+        if (issueTracking.provider === 'jira') {
+            if (!issueTracking.baseUrl || !issueTracking.projectKey) {
+                throw new Error('Jira issueTracking requires baseUrl and projectKey');
+            }
+            return;
+        }
+        if (issueTracking.provider === 'linear') {
+            if (!issueTracking.teamId) {
+                throw new Error('Linear issueTracking requires teamId');
+            }
+            return;
+        }
+        if (issueTracking.provider === 'gitlab') {
+            const hasProjectPath = typeof issueTracking.projectPath === 'string' && issueTracking.projectPath.length > 0;
+            const hasNamespaceAndName = typeof issueTracking.namespace === 'string' && issueTracking.namespace.length > 0 && typeof issueTracking.name === 'string' && issueTracking.name.length > 0;
+            if (!hasProjectPath && !hasNamespaceAndName) {
+                throw new Error('GitLab issueTracking requires projectPath or namespace + name');
+            }
+            return;
+        }
+        throw new Error(`Unsupported issueTracking provider: ${issueTracking.provider}`);
+    }
+    normalizeIssueTrackingConfig(issueTracking) {
+        if (!issueTracking || issueTracking.provider !== 'gitlab') {
+            return { ...issueTracking };
+        }
+        if (issueTracking.projectPath || !issueTracking.namespace || !issueTracking.name) {
+            return { ...issueTracking };
+        }
+        return {
+            ...issueTracking,
+            projectPath: `${issueTracking.namespace}/${issueTracking.name}`
+        };
+    }
+    /**
+     * Validate `evidence.quality` against REQUIRED_QUALITY_FIELDS.
+     * Thin wrapper around the pure core helper, preserved as a static
+     * method for existing test-quality-scores.ts imports.
+     */
+    static validateQualityEvidence(quality, jobName) {
+        return (0, quality_evidence_1.validateQualityEvidence)(quality, jobName);
+    }
+    buildQualityRejectionMessage(jobName, currentPhase, errors) {
+        return (0, quality_evidence_1.buildQualityRejectionMessage)(jobName, currentPhase, errors);
+    }
+    async maybeBuildPersonaLockResponse(jobName, userId, apiKey, consumeJobCredit = false) {
+        if (!(0, feature_flags_1.isPersonaEntitlementsEnabled)() || !userId) {
+            return null;
+        }
+        const decision = await (0, persona_entitlement_service_1.evaluatePersonaAccess)(this.dbService, userId, jobName, apiKey, `/fraim-brain?job=${encodeURIComponent(jobName)}`);
+        if (decision.allowed) {
+            if (consumeJobCredit && decision.entitlement?.hireMode === 'job' && decision.personaKey) {
+                const consumed = await this.dbService.consumePersonaJobCredit(decision.workspaceId, decision.personaKey);
+                if (!consumed) {
+                    const refreshedDecision = await (0, persona_entitlement_service_1.evaluatePersonaAccess)(this.dbService, userId, jobName, apiKey, `/fraim-brain?job=${encodeURIComponent(jobName)}`);
+                    if (!refreshedDecision.lock) {
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: 'This persona job credit is no longer available. Hire the persona again to continue.'
+                                }]
+                        };
+                    }
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `${refreshedDecision.lock.message}\n\n${refreshedDecision.lock.ctaLabel}: ${refreshedDecision.lock.hireUrl}`
+                            }],
+                        personaLock: {
+                            ...refreshedDecision.lock,
+                            jobName,
+                            workspaceId: refreshedDecision.workspaceId,
+                            ownedPersonaKeys: refreshedDecision.ownedPersonaKeys || []
+                        }
+                    };
+                }
+            }
+            return null;
+        }
+        if (!decision.lock) {
+            return null;
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `${decision.lock.message}\n\n${decision.lock.ctaLabel}: ${decision.lock.hireUrl}`
+                }],
+            personaLock: {
+                ...decision.lock,
+                jobName,
+                workspaceId: decision.workspaceId,
+                ownedPersonaKeys: decision.ownedPersonaKeys || []
+            }
+        };
+    }
+    async handleSeekMentoring(args, userId) {
+        const personaLock = await this.maybeBuildPersonaLockResponse(args.jobName, userId, undefined, args.status === 'starting');
+        if (personaLock) {
+            return personaLock;
+        }
+        // Validate jobId exists and belongs to the user
+        if (userId && this.analyticsService) {
+            const isValidJob = await this.analyticsService.validateJobId(args.jobId, userId);
+            if (!isValidJob) {
+                console.warn(`[seekMentoring] Unrecognized jobId: ${args.jobId} for user ${userId} — proceeding without tracking`);
+            }
+        }
+        const result = await this.aiMentor.handleMentoringRequest({
+            jobName: args.jobName,
+            issueNumber: args.issueNumber,
+            currentPhase: args.currentPhase,
+            status: args.status,
+            evidence: args.evidence,
+            findings: args.findings
+        });
+        // Quality enforcement (Issue #251): quality-producing jobs MUST emit
+        // a valid `evidence.quality` object on their final completion call.
+        //
+        // NOTE: In normal operation the local MCP proxy short-circuits
+        // seekMentoring (stdio-server.ts) and enforces the same contract
+        // there, so this server-side block is a FALL-THROUGH SAFETY NET.
+        // It only runs when the proxy's local AIMentor throws and the
+        // proxy falls through to proxying the call to the remote. The
+        // primary enforcement + quality-score emission path lives in
+        // stdio-server.ts around the seekMentoring short-circuit and the
+        // POST /api/analytics/quality-score endpoint in src/routes/analytics.ts.
+        const isQualityJob = exports.QUALITY_PRODUCING_JOBS.includes(args.jobName);
+        const isFinalCompletion = args.status === 'complete' &&
+            (result.nextPhase === null || result.nextPhase === undefined);
+        if (isQualityJob && isFinalCompletion) {
+            const qualityErrors = [
+                ...(McpService.validateQualityEvidence(args.evidence?.quality, args.jobName) || []),
+                ...(typeof args.evidence?.artifactPath === 'string' && args.evidence.artifactPath.trim()
+                    ? []
+                    : ['evidence.artifactPath is required'])
+            ];
+            if (qualityErrors.length > 0) {
+                const rejectionMessage = this.buildQualityRejectionMessage(args.jobName, args.currentPhase, qualityErrors);
+                if (userId && this.analyticsService) {
+                    try {
+                        const sessionId = args.sessionId || 'unknown';
+                        await this.analyticsService.logMentoringCall(args.jobId, args.jobName, userId, sessionId, args.currentPhase, 'incomplete', args.currentPhase, false);
+                    }
+                    catch (e) {
+                        console.error(`❌ McpService: Failed to log quality rejection:`, e);
+                    }
+                }
+                return {
+                    content: [{ type: 'text', text: rejectionMessage }]
+                };
+            }
+        }
+        // Update job execution tracking using usage events
+        if (userId && this.analyticsService) {
+            try {
+                const sessionId = args.sessionId || 'unknown';
+                await this.analyticsService.logMentoringCall(args.jobId, args.jobName, userId, sessionId, args.currentPhase, args.status, result.nextPhase, result.message ? true : false);
+                // Log explicit completion event when job finishes
+                if (result.nextPhase === null || result.nextPhase === undefined) {
+                    await this.analyticsService.logJobComplete(args.jobId, args.jobName, userId, sessionId, args.currentPhase);
+                    // Emit quality score for jobs that produce quality assessments (Issue #251).
+                    // Validation already happened above for quality-producing jobs, so this
+                    // call is guaranteed to receive `evidence.artifactPath` and a well-formed `evidence.quality` object.
+                    if (isQualityJob) {
+                        await this.analyticsService.logQualityScore(userId, args.jobName, args.jobId, sessionId, args.evidence.quality, args.evidence?.artifactPath, args.evidence?.reviewContext?.repoIdentifier, args.evidence?.reviewContext);
+                    }
+                }
+            }
+            catch (e) {
+                console.error(`❌ McpService: Failed to log mentoring/completion:`, e);
+            }
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: result.message
+                }]
+        };
+    }
+    getJobDescription(jobName, fullPath) {
+        if (fullPath && (0, fs_1.existsSync)(fullPath)) {
+            try {
+                const dynamicDesc = job_parser_1.JobParser.extractDescription(fullPath);
+                if (dynamicDesc && dynamicDesc.length > 5)
+                    return dynamicDesc;
+            }
+            catch (e) { }
+        }
+        return 'FRAIM Job';
+    }
+    /**
+     * Raw API handler — mirrors MCP tools but returns content WITHOUT include resolution or token substitution.
+     * Used exclusively by the local proxy to fetch content it can then resolve locally (personalized-employee first).
+     */
+    async handleToolRaw(tool, args) {
+        switch (tool) {
+            case 'get_fraim_file': {
+                const path = args.path;
+                if (!path)
+                    throw new Error('path is required');
+                // raw=true: skips include resolution and header injection
+                return this.handleGetFile(path, { raw: true });
+            }
+            case 'get_fraim_job': {
+                const jobName = args.job;
+                if (!jobName)
+                    throw new Error('job is required');
+                const result = await this.aiMentor.getJobOverview(jobName);
+                if (!result) {
+                    return { content: [{ type: 'text', text: `Job "${jobName}" not found.` }] };
+                }
+                return { content: [{ type: 'text', text: result.overview }] };
+            }
+            case 'seekMentoring': {
+                const result = await this.aiMentor.handleMentoringRequest({
+                    jobName: args.jobName,
+                    issueNumber: args.issueNumber,
+                    currentPhase: args.currentPhase,
+                    status: args.status,
+                    evidence: args.evidence,
+                    findings: args.findings,
+                    skipIncludes: true // ← the key difference: raw, no include resolution
+                });
+                return { content: [{ type: 'text', text: result.message }] };
+            }
+            default:
+                throw new Error(`Unknown raw tool: ${tool}`);
+        }
+    }
+    getAvailableJobs() {
+        const jobs = Array.from(this.registryService.getFileIndex().values()).filter(f => f.type === 'job' && !f.isStub);
+        return Array.from(new Set(jobs.map(f => f.name.replace('.md', ''))));
+    }
+}
+exports.McpService = McpService;