fraim 2.0.340 → 2.0.342

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

@@ -46,6 +46,7 @@ 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 handoff_contracts_1 = require("../core/handoff-contracts");
+const test_evidence_contract_1 = require("../core/test-evidence-contract");
 const feature_flags_1 = require("../config/feature-flags");
 const persona_entitlement_service_1 = require("./persona-entitlement-service");
 exports.DEFAULT_LAUNCH_PHRASE_MAPPINGS = {
@@ -69,6 +70,7 @@ function buildTrainingModeBlock(mode) {
 }
 class McpService {
     constructor(registryService, sessionManager, aiMentor, dbService, analyticsServiceOrVersion, serverVersion) {
+        this.phaseStartMarkers = new Map();
         this.registryService = registryService;
         this.sessionManager = sessionManager;
         this.aiMentor = aiMentor;
@@ -226,8 +228,8 @@ class McpService {
                     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');
+                if (!args.jobName || !args.issueNumber || !args.currentPhase || !args.status) {
+                    throw new Error('Arguments "jobName", "issueNumber", "currentPhase", and "status" are required for seekMentoring');
                 }
                 return await this.handleSeekMentoring(args, context.userId);
             case 'list_fraim_jobs':
@@ -546,8 +548,8 @@ class McpService {
             '- Use FRAIM when the user explicitly invokes FRAIM, names a FRAIM job, asks what FRAIM job to run, or the active surface has already selected a FRAIM job.',
             '- For ordinary requests, answer or work normally. Do not scan FRAIM stubs first.',
             '- If the user already named a job, call `get_fraim_job({ job: "<job-name>" })` directly.',
-            '- If routing is active and 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 when routing is active.',
+            '- If routing is active and local FRAIM job stubs are present under `fraim/ai-employee/jobs/` or `fraim/ai-manager/jobs/`, read that directory\'s `INDEX.md` first (name, one-line intent, and category per job) to choose the best job; open an individual stub only to confirm a shortlisted candidate, or fall back to scanning the stubs directly if no `INDEX.md` is present.',
+            '- Also check `fraim/personalized-employee/jobs/` (and its own `INDEX.md`, if present) for local job overrides or repo-specific jobs when routing is active.',
             '- If local stubs are missing, you cannot inspect workspace files, or the user asks for available jobs, call `list_fraim_jobs()` to view the full catalog.',
             '- If no exact or high-confidence job match exists, say that no FRAIM job matches and continue with normal tools or ask one concise clarification.',
             '- Use `get_fraim_file(...)` only for the specific skills or rules needed for the current task.',
@@ -692,10 +694,15 @@ class McpService {
         if (personaLock) {
             return personaLock;
         }
-        // Validate jobId exists and belongs to the user
-        if (userId && this.analyticsService) {
+        // Missing IDs still allow mentoring and session-scoped start matching.
+        // Unknown IDs must not produce analytics records for another run.
+        let trackingWarning = '';
+        let canTrackJob = Boolean(args.jobId && userId && this.analyticsService);
+        if (canTrackJob) {
             const isValidJob = await this.analyticsService.validateJobId(args.jobId, userId);
             if (!isValidJob) {
+                canTrackJob = false;
+                trackingWarning = `Job tracking notice: jobId \`${args.jobId}\` is unrecognized for this user; continuing without job analytics.\n\n`;
                 console.warn(`[seekMentoring] Unrecognized jobId: ${args.jobId} for user ${userId} — proceeding without tracking`);
             }
         }
@@ -744,10 +751,21 @@ class McpService {
                 : 'enforce';
             if (reviewHandoffApplies && enforcementMode === 'enforce') {
                 return {
-                    content: [{ type: 'text', text: (0, handoff_contracts_1.buildHandoffRejectionMessage)(args.currentPhase, missingField, handoffErrors) }]
+                    content: [{ type: 'text', text: trackingWarning + (0, handoff_contracts_1.buildHandoffRejectionMessage)(args.currentPhase, missingField, handoffErrors) }]
                 };
             }
         }
+        const testEvidenceErrors = (0, test_evidence_contract_1.validateTestEvidenceContract)({
+            currentPhase: args.currentPhase,
+            status: args.status,
+            findings: args.findings,
+            phases: handoffPhaseMap,
+        });
+        if (testEvidenceErrors.length > 0) {
+            return {
+                content: [{ type: 'text', text: trackingWarning + (0, test_evidence_contract_1.buildTestEvidenceRejectionMessage)(args.currentPhase, testEvidenceErrors) }]
+            };
+        }
         // Quality enforcement (Issue #251): quality-producing jobs MUST emit
         // a valid `evidence.quality` object on their final completion call.
         //
@@ -771,7 +789,7 @@ class McpService {
             ];
             if (qualityErrors.length > 0) {
                 const rejectionMessage = this.buildQualityRejectionMessage(args.jobName, args.currentPhase, qualityErrors);
-                if (userId && this.analyticsService) {
+                if (canTrackJob && 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);
@@ -781,17 +799,58 @@ class McpService {
                     }
                 }
                 return {
-                    content: [{ type: 'text', text: rejectionMessage }]
+                    content: [{ type: 'text', text: trackingWarning + rejectionMessage }]
                 };
             }
         }
+        // Only accepted calls update the marker. A rejected completion must
+        // leave its start available for the corrected completion request.
+        let phaseStartWarning = '';
+        const sessionId = typeof args.sessionId === 'string' ? args.sessionId.trim() : '';
+        const isPhaseCompletion = args.status === 'complete' || args.status === 'failure';
+        if (sessionId && sessionId !== 'unknown') {
+            const markerKey = JSON.stringify([userId ?? null, sessionId, args.jobName]);
+            const context = {
+                sessionId,
+                jobName: args.jobName,
+                phaseId: args.currentPhase,
+                ...(args.jobId ? { jobId: args.jobId } : {}),
+            };
+            const marker = this.phaseStartMarkers.get(markerKey);
+            const timestamp = new Date().toISOString();
+            if (args.status === 'starting') {
+                this.phaseStartMarkers.set(markerKey, (0, handoff_contracts_1.recordPhaseStart)(marker, { ...context, timestamp }));
+            }
+            else if (isPhaseCompletion) {
+                const inspection = (0, handoff_contracts_1.inspectPhaseCompletion)(marker, context);
+                if (inspection.missingStart)
+                    phaseStartWarning = (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase);
+                const completed = (0, handoff_contracts_1.commitPhaseCompletion)(marker, inspection, { ...context, timestamp });
+                this.phaseStartMarkers.set(markerKey, completed);
+                if (args.status === 'complete' && result.nextPhase === null) {
+                    // Concurrent runs can share the session and job name.
+                    // Clear only this run (including starts before its ID was known).
+                    const completedJobId = args.jobId || completed.phaseInstances?.find((instance) => instance.instanceId === inspection.instanceId)?.jobId;
+                    const remaining = completed.phaseInstances?.filter((instance) => instance.jobId && instance.jobId !== completedJobId) || [];
+                    if (remaining.length > 0) {
+                        this.phaseStartMarkers.set(markerKey, { phaseInstances: remaining });
+                    }
+                    else {
+                        this.phaseStartMarkers.delete(markerKey);
+                    }
+                }
+            }
+        }
+        else if (isPhaseCompletion) {
+            phaseStartWarning = `Phase-start notice: phase \`${args.currentPhase}\` has no identifiable session, so its start cannot be matched to this run. The missing match was flagged, but this completion remains accepted.\n\n`;
+        }
         // Update job execution tracking using usage events
-        if (userId && this.analyticsService) {
+        if (canTrackJob && 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) {
+                if (args.status === 'complete' && result.nextPhase === null) {
                     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
@@ -818,8 +877,9 @@ class McpService {
         return {
             content: [{
                     type: 'text',
-                    text: result.message
-                }]
+                    text: trackingWarning + phaseStartWarning + result.message
+                }],
+            structuredContent: { phaseAccepted: true, nextPhase: result.nextPhase, phaseStartWarning }
         };
     }
     getJobDescription(jobName, fullPath) {

package/dist/src/services/usage-analytics-service.js

@@ -63,9 +63,10 @@ class UsageAnalyticsService {
         }
     }
     /**
-     * Log a usage event immediately (bypasses queue)
+     * Log a usage event immediately (bypasses queue).
+     * Ingestion callers can require persistence; other callers remain best effort.
      */
-    async logUsageImmediate(input) {
+    async logUsageImmediate(input, options = {}) {
         try {
             // Enrich with category if missing and type is job
             if (input.type === 'job' && (!input.category || input.category === 'uncategorized')) {
@@ -75,7 +76,9 @@ class UsageAnalyticsService {
         }
         catch (error) {
             console.error('Failed to log usage event:', error);
-            // Don't throw - analytics failures shouldn't break main functionality
+            if (options.throwOnError)
+                throw error;
+            // Analytics failures should not break unrelated main functionality.
         }
     }
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fraim",
-  "version": "2.0.340",
+  "version": "2.0.342",
   "description": "FRAIM core CLI and MCP package.",
   "main": "index.js",
   "bin": {