@microsoft/m365-copilot-eval 1.5.0-preview.1 → 1.6.0-preview.1

package/README.md

@@ -24,6 +24,7 @@ A CLI for evaluating M365 Copilot agents. Send prompts to your agent, get respon
 - **M365 Copilot License** for your tenant
 - **M365 Copilot Agent** deployed to your tenant (can be created with [M365 Agents Toolkit](https://learn.microsoft.com/en-us/microsoft-365/developer/overview-m365-agents-toolkit) or any other method)
 - **Node.js 24.12.0+** (check: `node --version`)
+- **Python 3.13.x** is downloaded automatically. If the download fails (e.g., network restrictions), set `PYTHON_PATH` to a local Python 3.13.x installation (see [Troubleshooting](#-troubleshooting))
 - **Environment file** with your credentials and agent ID (see [Environment Setup](#-environment-setup) below)
 - **Your Tenant ID** - get your tenant id using the instructions [here](https://learn.microsoft.com/en-us/azure/azure-portal/get-subscription-tenant-id) 
 - Admin approval to run WORKIQ Client App for your tenant [here](https://github.com/microsoft/work-iq/blob/main/ADMIN-INSTRUCTIONS.md)
@@ -460,6 +461,20 @@ runevals cache-dir
 chmod -R u+w $(runevals cache-dir)
 ```
 
+### Custom Python Runtime (PYTHON_PATH)
+
+If the automatic Python download fails (e.g., network restrictions, unsupported platform), provide your own Python installation:
+
+```bash
+# Windows
+set PYTHON_PATH=C:\Python313\python.exe
+
+# macOS/Linux
+export PYTHON_PATH=/usr/local/bin/python3.13
+```
+
+Python 3.13.x is the tested version. If a different version is found, you'll be prompted to confirm before proceeding. In CI/CD, a version mismatch fails automatically.
+
 ## 📚 Advanced Documentation
 
 - **[CI/CD Integration](./CICD_CACHE_GUIDE.md)** - GitHub Actions, Azure DevOps caching

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@microsoft/m365-copilot-eval",
-  "version": "1.5.0-preview.1",
+  "version": "1.6.0-preview.1",
   "minCliVersion": "1.0.1-preview.1",
   "description": "Zero-config Node.js wrapper for M365 Copilot Agent Evaluations CLI (Python-based Azure AI Evaluation SDK)",
-  "publishDate": "2026-04-30",
+  "publishDate": "2026-05-07",
   "main": "src/clients/node-js/lib/index.js",
   "type": "module",
   "bin": {
@@ -80,8 +80,9 @@
     "README.md",
     "LICENSE"
   ],
+  "homepage": "https://github.com/microsoft/m365-copilot-eval",
   "repository": {
     "type": "git",
-    "url": "https://github.com/microsoft/M365-Copilot-Agent-Evals.git"
+    "url": "https://github.com/microsoft/m365-copilot-eval.git"
   }
 }

package/schema/CHANGELOG.md

@@ -5,6 +5,13 @@ All notable changes to the eval document schema will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.0](https://github.com/microsoft/M365-Copilot-Agent-Evals/compare/schema-v1.2.0...schema-v1.3.0) (2026-04-30)
+
+
+### Features
+
+* Added similarity evaluator for compatibility with MCS Evals. ([#228](https://github.com/microsoft/M365-Copilot-Agent-Evals/issues/228)) ([0fe8315](https://github.com/microsoft/M365-Copilot-Agent-Evals/commit/0fe8315abc8e0422d1ac9117fe9f29195f29044f))
+
 ## [1.2.0](https://github.com/microsoft/M365-Copilot-Agent-Evals/compare/schema-v1.1.0...schema-v1.2.0) (2026-04-22)
 
 

package/schema/version.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.3.0",
   "releaseDate": "2026-04-02",
   "schemaId": "https://raw.githubusercontent.com/microsoft/M365-Copilot-Agent-Evals/refs/heads/main/schema/v1/eval-document.schema.json",
   "description": "M365 Copilot Eval Document Schema"

package/src/clients/cli/api_clients/A2A/a2a_client.py

@@ -8,7 +8,7 @@ import re
 import urllib.error
 import urllib.request
 import uuid
-from typing import Any, Dict, List, Optional, Tuple
+from typing import Any, Callable, Dict, List, Optional, Tuple
 
 from api_clients.base_agent_client import BaseAgentClient
 from cli_logging.console_diagnostics import emit_structured_log
@@ -35,6 +35,7 @@ class A2AClient(BaseAgentClient):
         access_token: str,
         logger: Optional[logging.Logger] = None,
         diagnostic_records: Optional[List[Dict[str, Any]]] = None,
+        token_refresh_fn: Optional[Callable[[], str]] = None,
     ) -> None:
         """
         Args:
@@ -42,11 +43,15 @@ class A2AClient(BaseAgentClient):
             access_token: Bearer token for A2A authentication.
             logger: Logger to use. Defaults to a module-level logger if not provided.
             diagnostic_records: List to accumulate structured log entries.
+            token_refresh_fn: Optional callable that returns a fresh access token string.
+                When provided, a single HTTP 401 response will trigger a token refresh
+                and one automatic retry, making the refresh invisible to the caller.
         """
         self._endpoint = a2a_endpoint.rstrip("/")
         self._access_token = access_token
         self._logger = logger or logging.getLogger(__name__)
         self._diagnostic_records = diagnostic_records
+        self._token_refresh_fn = token_refresh_fn
         self._resolved_agent_url: Optional[str] = None
 
     # ------------------------------------------------------------------ #
@@ -261,6 +266,12 @@ class A2AClient(BaseAgentClient):
     ) -> tuple[Dict[str, Any], Dict[str, Any]]:
         """Send a JSON-RPC message to the agent and parse the response.
 
+        When a ``token_refresh_fn`` was supplied at construction time and the
+        server responds with HTTP 401 (Unauthorized), the token is refreshed
+        automatically and the request is retried exactly once.  This keeps
+        long-running eval sessions alive beyond the initial token lifetime
+        without requiring any user interaction.
+
         Returns:
             A tuple of (result_dict, raw_result) where result_dict is the
             normalized response dict (raw_response_text, display_response_text,
@@ -275,15 +286,51 @@ class A2AClient(BaseAgentClient):
             with urllib.request.urlopen(req, timeout=_REQUEST_TIMEOUT_SECS) as resp:
                 raw = resp.read().decode("utf-8", errors="replace")
         except urllib.error.HTTPError as e:
-            body = ""
-            try:
-                body = e.read().decode("utf-8", errors="replace")
-            except Exception:
-                pass
-            raise RuntimeError(
-                f"A2A request failed (HTTP {e.code} {e.reason})."
-                + (f" Body: {body[:500]}" if body else "")
-            ) from e
+            if e.code == 401 and self._token_refresh_fn is not None:
+                emit_structured_log(
+                    "info",
+                    "[A2A] Access token expired (HTTP 401); refreshing token and retrying.",
+                    Operation.AUTHENTICATE,
+                    logger=self._logger,
+                    diagnostic_records=self._diagnostic_records,
+                )
+                new_token = self._token_refresh_fn()
+                if not new_token:
+                    raise RuntimeError(
+                        "A2A request failed (HTTP 401 Unauthorized) and token refresh returned no token."
+                    ) from e
+                self._access_token = new_token
+                headers["Authorization"] = f"Bearer {self._access_token}"
+                retry_req = urllib.request.Request(
+                    agent_url, data=payload, headers=headers, method="POST"
+                )
+                try:
+                    with urllib.request.urlopen(retry_req, timeout=_REQUEST_TIMEOUT_SECS) as resp:
+                        raw = resp.read().decode("utf-8", errors="replace")
+                except urllib.error.HTTPError as retry_e:
+                    body = ""
+                    try:
+                        body = retry_e.read().decode("utf-8", errors="replace")
+                    except Exception:
+                        pass
+                    raise RuntimeError(
+                        f"A2A request failed (HTTP {retry_e.code} {retry_e.reason}) after token refresh."
+                        + (f" Body: {body[:500]}" if body else "")
+                    ) from retry_e
+                except urllib.error.URLError as retry_e:
+                    raise RuntimeError(
+                        f"A2A connection error after token refresh: {getattr(retry_e, 'reason', str(retry_e))}"
+                    ) from retry_e
+            else:
+                body = ""
+                try:
+                    body = e.read().decode("utf-8", errors="replace")
+                except Exception:
+                    pass
+                raise RuntimeError(
+                    f"A2A request failed (HTTP {e.code} {e.reason})."
+                    + (f" Body: {body[:500]}" if body else "")
+                ) from e
         except urllib.error.URLError as e:
             raise RuntimeError(
                 f"A2A connection error: {getattr(e, 'reason', str(e))}"

package/src/clients/cli/auth/auth_handler.py

@@ -13,7 +13,7 @@ https://github.com/AzureAD/microsoft-authentication-extensions-for-python
 import os
 import platform
 import logging
-from typing import Optional
+from typing import Callable, Optional
 from pathlib import Path
 import jwt
 from msal import PublicClientApplication
@@ -260,3 +260,23 @@ class AuthHandler:
             return oid
         except jwt.DecodeError as e:
             raise ValueError(f"Failed to decode token: {e}")
+
+
+def make_token_refresh_fn(auth_handler: "AuthHandler") -> Callable[[], str]:
+    """Return a callable that silently refreshes the A2A access token.
+
+    On a 401 response the caller invokes this function.  It first attempts a
+    silent refresh (using the MSAL refresh token) and falls back to interactive
+    authentication only when a silent refresh is not possible.  The returned
+    string is the new access token; an empty string signals failure.
+
+    Args:
+        auth_handler: An initialized AuthHandler instance to use for token acquisition.
+
+    Returns:
+        A zero-argument callable that returns a fresh access token string.
+    """
+    def _refresh() -> str:
+        result = auth_handler.acquire_token_interactive() or {}
+        return result.get("access_token") or ""
+    return _refresh

package/src/clients/cli/main.py

@@ -16,7 +16,7 @@ from azure.ai.evaluation import AzureOpenAIModelConfiguration
 from dotenv import load_dotenv
 
 from api_clients.A2A import A2AClient
-from auth.auth_handler import AuthHandler
+from auth.auth_handler import AuthHandler, make_token_refresh_fn
 from evaluator_resolver import resolve_default_evaluators
 from version_check import check_min_version, get_cli_version
 
@@ -122,6 +122,7 @@ def main():
         agent_client = A2AClient(
             a2a_endpoint=a2a_endpoint,
             access_token=a2a_access_token,
+            token_refresh_fn=make_token_refresh_fn(a2a_auth_handler),
             logger=CLI_LOGGER,
             diagnostic_records=DIAGNOSTIC_RECORDS,
         )

package/src/clients/node-js/bin/runevals.js

@@ -9,8 +9,13 @@ import { ensureVenv, executePythonCli } from '../lib/venv-manager.js';
 import { getCacheStats, clearCache, formatBytes } from '../lib/cache-utils.js';
 import { checkPackageExpiry } from '../lib/expiry-check.js';
 import { recordAcceptance, checkAcceptance } from '../lib/eula-manager.js';
-import { ProgressReporter } from '../lib/progress.js';
+import { ProgressReporter, isInteractiveTerminal } from '../lib/progress.js';
 import { _loadEnvFile as loadEnvFile, _loadUserEnvOverride } from '../lib/env-loader.js';
+import {
+  _handlePythonVersionMismatch,
+  _buildInitializationFailureLines,
+  _promptForContinueWithMismatch,
+} from '../lib/version-check.js';
 import { normalizeAgentId } from '../lib/agent-id.js';
 
 // Check package expiry (exits if expired, warns if close to expiry)
@@ -130,10 +135,26 @@ async function initializePythonEnvironment(verbose = false, quiet = false) {
 
   try {
     // Step 1: Ensure Python runtime is available (handles download + extract phases)
-    await ensurePythonRuntime(verbose, onProgress);
+    const runtime = await ensurePythonRuntime(verbose, onProgress);
+
+    // Step 2: Handle version mismatch from PYTHON_PATH fallback.
+    // The decision tree (EOL block, interactive prompt, non-interactive
+    // auto-reject) lives in _handlePythonVersionMismatch so it is
+    // unit-testable without spawning the CLI; we only own the readline
+    // wiring and the actual process.exit here.
+    const mismatch = await _handlePythonVersionMismatch({
+      runtime,
+      isInteractive: isInteractiveTerminal(),
+      promptForContinue: _promptForContinueWithMismatch,
+      warn: (msg) => console.warn(msg),
+      error: (msg) => console.error(msg),
+    });
+    if (mismatch.shouldExit) {
+      process.exit(mismatch.exitCode ?? 1);
+    }
 
-    // Step 2: Ensure venv with dependencies is set up (handles venv + deps phases)
-    await ensureVenv(REQUIREMENTS_FILE, verbose, onProgress);
+    // Step 3: Ensure venv with dependencies is set up (handles venv + deps phases)
+    await ensureVenv(REQUIREMENTS_FILE, verbose, onProgress, runtime.pythonPath);
 
     // Show completion summary
     reporter.complete();
@@ -144,11 +165,12 @@ async function initializePythonEnvironment(verbose = false, quiet = false) {
       console.error('\nFull error:', error);
     }
 
-    console.error('\nTroubleshooting:');
-    console.error('  - Check your internet connection');
-    console.error('  - If behind a proxy, set HTTP_PROXY/HTTPS_PROXY environment variables');
-    console.error('  - For SSL issues, set NODE_EXTRA_CA_CERTS or PIP_CERT');
-    console.error('  - Run with --log-level debug for detailed output');
+    for (const line of _buildInitializationFailureLines({
+      error,
+      platform: process.platform,
+    })) {
+      console.error(line);
+    }
 
     process.exit(1);
   }

package/src/clients/node-js/config/default.js

@@ -2,7 +2,7 @@
  * Build-time injected default values
  * DO NOT EDIT - This file is auto-generated during build.
  *
- * Generated: 2026-04-30T18:03:21.788Z
+ * Generated: 2026-05-07T22:53:22.056Z
  *
  * @copyright Microsoft Corporation. All rights reserved.
  * @license MIT

package/src/clients/node-js/lib/python-runtime.js

@@ -5,6 +5,10 @@ import crypto from 'crypto';
 import { pipeline } from 'stream/promises';
 import { createWriteStream } from 'fs';
 import { Transform } from 'stream';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+
+const execFileAsync = promisify(execFile);
 import fetch from 'node-fetch';
 
 /**
@@ -14,7 +18,7 @@ import fetch from 'node-fetch';
 
 // PBS release version (latest release with Python 3.13.10)
 const PBS_VERSION = '20251202';
-const PYTHON_VERSION = '3.13.10';
+export const PYTHON_VERSION = '3.13.10';
 
 // Base URL for PBS releases
 const PBS_BASE_URL = `https://github.com/indygreg/python-build-standalone/releases/download/${PBS_VERSION}`;
@@ -212,66 +216,111 @@ async function extractTarGz(archivePath, destDir, onProgress) {
 }
 
 /**
- * Download and setup Python Build Standalone runtime
- * Returns the path to the Python executable
- * @param {boolean} [verbose=false] - Enable verbose output
- * @param {Function} [onProgress] - Optional progress callback
+ * Validate that a Python executable is the expected version.
+ * @param {string} pythonPath - Path to a Python executable
+ * @returns {{ isMatch: boolean, version: string }} Version info
  */
-export async function ensurePythonRuntime(verbose = false, onProgress) {
-  const platformKey = getPlatformKey();
-  const distribution = PBS_DISTRIBUTIONS[platformKey];
-
-  const cacheDir = getCacheDir();
-  const pythonDir = path.join(
-    cacheDir,
-    'python',
-    `${PYTHON_VERSION}-${platformKey}`
-  );
-  const archivePath = path.join(cacheDir, 'downloads', distribution.filename);
-
-  // Determine Python executable path based on platform
-  const pythonExe =
-    process.platform === 'win32'
-      ? path.join(pythonDir, 'python.exe')
-      : path.join(pythonDir, 'bin', 'python3');
-
-  // Check if Python is already installed (silent skip per FR-007)
+export async function _validatePythonVersion(pythonPath) {
+  const expectedMajorMinor = PYTHON_VERSION.split('.').slice(0, 2).join('.');
   try {
-    await fs.access(pythonExe);
-    if (verbose) {
-      console.log(`Using cached Python runtime: ${pythonExe}`);
+    const { stdout } = await execFileAsync(pythonPath, ['--version'], {
+      encoding: 'utf8',
+      timeout: 10_000,
+    });
+    // Output format: "Python 3.13.10"
+    const match = stdout.trim().match(/Python\s+(\d+\.\d+\.\d+)/);
+    if (!match) {
+      return { isMatch: false, version: 'unknown' };
     }
-    // Skip both download and extract phases silently
-    onProgress?.({ type: 'skip', phaseId: 'download' });
-    onProgress?.({ type: 'skip', phaseId: 'extract' });
-    return pythonExe;
+    const version = match[1];
+    const majorMinor = version.split('.').slice(0, 2).join('.');
+    return { isMatch: majorMinor === expectedMajorMinor, version };
   } catch {
-    // Python not found, proceed with download and extraction
+    return { isMatch: false, version: 'unknown' };
   }
+}
 
-  if (!onProgress) {
-    console.log(
-      `Setting up Python ${PYTHON_VERSION} runtime for ${platformKey}...`
-    );
+/**
+ * Attempt to resolve a fallback Python from the PYTHON_PATH environment variable.
+ * @returns {Promise<{ pythonPath: string, version: string, isMatch: boolean }>}
+ */
+export async function _resolveFallbackPython() {
+  const pythonPath = process.env.PYTHON_PATH;
+  if (!pythonPath) {
+    throw new Error('PYTHON_PATH environment variable is not set.');
   }
 
-  // Download if not cached
-  let needsDownload = false;
+  await fs.access(pythonPath);
+  const { isMatch, version } = await _validatePythonVersion(pythonPath);
+  return { pythonPath, version, isMatch };
+}
+
+/**
+ * Download and setup Python Build Standalone runtime
+ * Returns the path to the Python executable and version info.
+ * On download failure, falls back to PYTHON_PATH env var if available.
+ * @param {boolean} [verbose=false] - Enable verbose output
+ * @param {Function} [onProgress] - Optional progress callback
+ * @returns {Promise<{ pythonPath: string, version: string, isMatch: boolean }>}
+ */
+export async function ensurePythonRuntime(verbose = false, onProgress) {
+  // Attempt PBS download + extraction; falls back to PYTHON_PATH on any failure
+  // (including unsupported platform where getPlatformKey() throws)
+  let currentPhase = 'download';
   try {
-    await fs.access(archivePath);
-    if (verbose) {
-      console.log('Using cached download');
+    const platformKey = getPlatformKey();
+    const distribution = PBS_DISTRIBUTIONS[platformKey];
+
+    const cacheDir = getCacheDir();
+    const pythonDir = path.join(
+      cacheDir,
+      'python',
+      `${PYTHON_VERSION}-${platformKey}`
+    );
+    const archivePath = path.join(cacheDir, 'downloads', distribution.filename);
+
+    // Determine Python executable path based on platform
+    const pythonExe =
+      process.platform === 'win32'
+        ? path.join(pythonDir, 'python.exe')
+        : path.join(pythonDir, 'bin', 'python3');
+
+    // Check if Python is already installed (silent skip per FR-007)
+    try {
+      await fs.access(pythonExe);
+      if (verbose) {
+        console.log(`Using cached Python runtime: ${pythonExe}`);
+      }
+      // Skip both download and extract phases silently
+      onProgress?.({ type: 'skip', phaseId: 'download' });
+      onProgress?.({ type: 'skip', phaseId: 'extract' });
+      return { pythonPath: pythonExe, version: PYTHON_VERSION, isMatch: true };
+    } catch {
+      // Python not found, proceed with download and extraction
     }
-    // Skip download phase silently
-    onProgress?.({ type: 'skip', phaseId: 'download' });
-  } catch {
-    needsDownload = true;
-  }
 
-  if (needsDownload) {
-    // Start download phase
-    onProgress?.({ type: 'start', phaseId: 'download' });
+    if (!onProgress) {
+      console.log(
+        `Setting up Python ${PYTHON_VERSION} runtime for ${platformKey}...`
+      );
+    }
+
+    // Download if not cached
+    let needsDownload = false;
     try {
+      await fs.access(archivePath);
+      if (verbose) {
+        console.log('Using cached download');
+      }
+      // Skip download phase silently
+      onProgress?.({ type: 'skip', phaseId: 'download' });
+    } catch {
+      needsDownload = true;
+    }
+
+    if (needsDownload) {
+      // Start download phase
+      onProgress?.({ type: 'start', phaseId: 'download' });
       const downloadUrl = `${PBS_BASE_URL}/${distribution.filename}`;
       await downloadFile(
         downloadUrl,
@@ -280,29 +329,52 @@ export async function ensurePythonRuntime(verbose = false, onProgress) {
         onProgress
       );
       onProgress?.({ type: 'complete', phaseId: 'download' });
-    } catch (error) {
-      onProgress?.({ type: 'error', phaseId: 'download', error });
-      throw error;
     }
-  }
 
-  // Extract phase
-  onProgress?.({ type: 'start', phaseId: 'extract' });
-  try {
+    // Extract phase
+    currentPhase = 'extract';
+    onProgress?.({ type: 'start', phaseId: 'extract' });
     await extractTarGz(archivePath, pythonDir, onProgress);
     onProgress?.({ type: 'complete', phaseId: 'extract' });
-  } catch (error) {
-    onProgress?.({ type: 'error', phaseId: 'extract', error });
-    throw error;
-  }
 
-  // Verify Python executable exists
-  await fs.access(pythonExe);
+    // Verify Python executable exists
+    await fs.access(pythonExe);
 
-  if (!onProgress) {
-    console.log(`Python runtime ready: ${pythonExe}`);
+    if (!onProgress) {
+      console.log(`Python runtime ready: ${pythonExe}`);
+    }
+    return { pythonPath: pythonExe, version: PYTHON_VERSION, isMatch: true };
+  } catch (pbsError) {
+    // PBS setup failed (unsupported platform, download, or extract) — attempt PYTHON_PATH fallback
+    onProgress?.({ type: 'error', phaseId: currentPhase, error: pbsError });
+
+    if (verbose) {
+      console.error(
+        `Python setup failed: ${pbsError.message}. Checking PYTHON_PATH fallback...`
+      );
+    }
+
+    try {
+      const fallback = await _resolveFallbackPython();
+      if (verbose) {
+        console.log(
+          `Using PYTHON_PATH fallback: ${fallback.pythonPath} (Python ${fallback.version})`
+        );
+      }
+      // Mark extract as skipped since we're using an external Python
+      onProgress?.({ type: 'skip', phaseId: 'extract' });
+      return fallback;
+    } catch (fallbackError) {
+      // Neither PBS nor PYTHON_PATH worked
+      const err = new Error(
+        `Python ${PYTHON_VERSION} could not be set up.\n` +
+          `  PBS setup failed: ${pbsError.message}\n` +
+          `  PYTHON_PATH fallback: ${fallbackError.message}`
+      );
+      err.code = 'PYTHON_NOT_FOUND';
+      throw err;
+    }
   }
-  return pythonExe;
 }
 
 /**

package/src/clients/node-js/lib/venv-manager.js

@@ -321,9 +321,10 @@ async function writeRequirementsMarker(venvDir, requirementsHash) {
 export async function ensureVenv(
   requirementsPath,
   verbose = false,
-  onProgress
+  onProgress,
+  pythonExePath
 ) {
-  const pythonExe = await getPythonExecutable();
+  const pythonExe = pythonExePath || (await getPythonExecutable());
   const venvDir = getVenvDir();
   const requirementsHash = await getRequirementsHash(requirementsPath);
 

package/src/clients/node-js/lib/version-check.js

@@ -0,0 +1,268 @@
+import { PYTHON_VERSION } from './python-runtime.js';
+
+/**
+ * Minimum Python major.minor that is still receiving security updates.
+ *
+ * This MUST be reviewed against the official Python release schedule
+ * (https://devguide.python.org/versions/) when bumping PYTHON_VERSION
+ * or whenever a previously supported branch reaches end-of-life.
+ *
+ * Versions older than this are hard-blocked because they no longer
+ * receive security patches and pose a supply-chain risk to users.
+ */
+export const MIN_SUPPORTED_PYTHON_MAJOR_MINOR = '3.10';
+
+/**
+ * Parse a version string into { major, minor }, or null if it cannot
+ * be parsed (e.g. the literal string 'unknown').
+ * @param {string} version
+ * @returns {{ major: number, minor: number } | null}
+ */
+function parseMajorMinor(version) {
+  const match = String(version).match(/^(\d+)\.(\d+)/);
+  if (!match) return null;
+  return { major: parseInt(match[1], 10), minor: parseInt(match[2], 10) };
+}
+
+/**
+ * Returns true when the detected Python version is older than the
+ * minimum supported major.minor and is therefore considered EOL.
+ *
+ * Returns false for unparseable versions (e.g. 'unknown') so the
+ * caller's regular version-mismatch flow can handle them.
+ *
+ * @param {string} version - Detected Python version string (e.g. "3.8.10")
+ * @returns {boolean}
+ */
+export function _isPythonVersionEol(version) {
+  const detected = parseMajorMinor(version);
+  if (!detected) return false;
+  const min = parseMajorMinor(MIN_SUPPORTED_PYTHON_MAJOR_MINOR);
+  if (detected.major < min.major) return true;
+  if (detected.major === min.major && detected.minor < min.minor) return true;
+  return false;
+}
+
+/**
+ * Build the user-facing error message for an EOL Python version that
+ * has been hard-blocked. EOL versions are blocked unconditionally
+ * (no override prompt) because they no longer receive security fixes.
+ *
+ * @param {string} version - Detected Python version string
+ * @returns {string[]} Array of lines to print
+ */
+export function _formatEolPythonError(version) {
+  return [
+    `\n❌ Python ${version} has reached end-of-life and is not supported.`,
+    '   Continuing would expose you to known security vulnerabilities,',
+    '   so this version is blocked unconditionally.\n',
+    `   Minimum supported version: Python ${MIN_SUPPORTED_PYTHON_MAJOR_MINOR}`,
+    `   Recommended version:       Python ${PYTHON_VERSION}`,
+    '   Python release schedule:   https://devguide.python.org/versions/',
+    '   Download a supported build: https://www.python.org/downloads/\n',
+  ];
+}
+
+/**
+ * Build the user-facing error message for PYTHON_NOT_FOUND failures.
+ * @param {string} platform - process.platform value
+ * @returns {string[]} Array of lines to print
+ */
+export function _formatPythonNotFoundError(platform) {
+  const lines = [
+    `\n❌ Python ${PYTHON_VERSION} is required but could not be found.\n`,
+    'The automatic download failed, and no valid fallback was detected.',
+    'To provide Python manually, set the PYTHON_PATH environment variable:\n',
+  ];
+
+  if (platform === 'win32') {
+    lines.push('  set PYTHON_PATH=C:\\path\\to\\python.exe');
+  } else {
+    lines.push('  export PYTHON_PATH=/path/to/python3');
+  }
+
+  lines.push(
+    `\nRequired version: Python ${PYTHON_VERSION}`,
+    'Download: https://www.python.org/downloads/\n'
+  );
+
+  return lines;
+}
+
+/**
+ * Evaluate what action to take when the resolved Python version doesn't match.
+ *
+ * EOL versions are hard-rejected even when the user answers "yes" — this
+ * defends against the y/n prompt being used to bypass the security gate
+ * and is checked here in addition to the upfront check in the CLI.
+ *
+ * @param {string} version - The detected Python version string
+ * @param {{ isInteractive: boolean, promptAnswer?: string }} options
+ * @returns {{ action: 'continue' | 'reject', reason: string }}
+ */
+export function _evaluateVersionMismatch(
+  version,
+  { isInteractive, promptAnswer }
+) {
+  if (_isPythonVersionEol(version)) {
+    return {
+      action: 'reject',
+      reason: `Python ${version} has reached end-of-life and cannot be used. Install Python ${MIN_SUPPORTED_PYTHON_MAJOR_MINOR} or newer (Python ${PYTHON_VERSION} recommended).`,
+    };
+  }
+
+  if (!isInteractive) {
+    return {
+      action: 'reject',
+      reason: `Python version mismatch (found ${version}). In non-interactive environments, PYTHON_PATH must point to Python ${PYTHON_VERSION}.`,
+    };
+  }
+
+  const answer = (promptAnswer || '').trim().toLowerCase();
+  if (answer === 'y' || answer === 'yes') {
+    return { action: 'continue', reason: 'User accepted version mismatch.' };
+  }
+
+  return {
+    action: 'reject',
+    reason: `Aborted. Please install Python ${PYTHON_VERSION} or set PYTHON_PATH to a compatible version.`,
+  };
+}
+
+/**
+ * Handle a Python version mismatch with side effects routed through
+ * injected callbacks so the full decision tree is unit-testable without
+ * touching real stdout/stderr, readline, or process.exit.
+ *
+ * Behaviour mirrors the inline block previously in runevals.js:
+ *   - EOL versions are hard-blocked (no prompt) regardless of interactivity.
+ *   - Interactive terminals warn, prompt, and respect the user's answer
+ *     (subject to the EOL block enforced inside _evaluateVersionMismatch).
+ *   - Non-interactive environments auto-reject.
+ *
+ * @param {object} args
+ * @param {{ version: string, isMatch: boolean }} args.runtime - Detected runtime info.
+ * @param {boolean} args.isInteractive - Whether we are in an interactive terminal.
+ * @param {() => Promise<string>} [args.promptForContinue] - Async function that
+ *   resolves with the user's y/n answer. Required when isInteractive is true.
+ * @param {(msg: string) => void} args.warn - Sink for warning messages.
+ * @param {(msg: string) => void} args.error - Sink for error messages.
+ * @returns {Promise<{ shouldExit: boolean, exitCode?: number }>}
+ *   When `shouldExit` is true the caller should `process.exit(exitCode)`.
+ *   When false, initialization may continue with the mismatched runtime.
+ */
+export async function _handlePythonVersionMismatch({
+  runtime,
+  isInteractive,
+  promptForContinue,
+  warn,
+  error,
+}) {
+  if (runtime.isMatch) {
+    return { shouldExit: false };
+  }
+
+  if (_isPythonVersionEol(runtime.version)) {
+    for (const line of _formatEolPythonError(runtime.version)) {
+      error(line);
+    }
+    return { shouldExit: true, exitCode: 1 };
+  }
+
+  if (isInteractive) {
+    warn(
+      `\n⚠️  Python version mismatch. Expected ${PYTHON_VERSION}, found ${runtime.version}.`
+    );
+
+    const answer = await promptForContinue();
+
+    const result = _evaluateVersionMismatch(runtime.version, {
+      isInteractive: true,
+      promptAnswer: answer,
+    });
+    if (result.action === 'reject') {
+      error(`\n${result.reason}`);
+      error('Download: https://www.python.org/downloads/\n');
+      return { shouldExit: true, exitCode: 1 };
+    }
+    return { shouldExit: false };
+  }
+
+  // Non-interactive (CI/CD) — auto-reject version mismatch
+  const result = _evaluateVersionMismatch(runtime.version, {
+    isInteractive: false,
+  });
+  error(`\n❌ ${result.reason}`);
+  return { shouldExit: true, exitCode: 1 };
+}
+
+/**
+ * Build the user-facing error guidance lines printed when Python
+ * environment initialization fails. Returns the lines as an array so
+ * the caller can route them to console.error and the result is testable
+ * without intercepting console.
+ *
+ * If `error.code === 'PYTHON_NOT_FOUND'`, the platform-specific
+ * PYTHON_NOT_FOUND guidance is included before the generic troubleshooting
+ * tips.
+ *
+ * @param {{ error: { code?: string }, platform: string }} args
+ * @returns {string[]}
+ */
+export function _buildInitializationFailureLines({ error, platform }) {
+  const lines = [];
+
+  if (error && error.code === 'PYTHON_NOT_FOUND') {
+    for (const line of _formatPythonNotFoundError(platform)) {
+      lines.push(line);
+    }
+  }
+
+  lines.push(
+    'Troubleshooting:',
+    '  - Check your internet connection',
+    '  - If behind a proxy, set HTTP_PROXY/HTTPS_PROXY environment variables',
+    '  - For SSL issues, set NODE_EXTRA_CA_CERTS or PIP_CERT',
+    '  - Run with --log-level debug for detailed output'
+  );
+
+  return lines;
+}
+
+/**
+ * Prompt the user to continue past a Python version mismatch.
+ *
+ * The readline factory is injected so this can be unit-tested with a
+ * fake interface. The default factory uses Node's built-in readline
+ * bound to process.stdin/process.stdout. The interface is always
+ * closed via try/finally so a Ctrl+C does not leave the event loop
+ * holding stdin open.
+ *
+ * @param {object} [deps]
+ * @param {() => { question: (q: string, cb: (answer: string) => void) => void, close: () => void }} [deps.createInterface]
+ *   Factory returning a readline-compatible interface.
+ * @returns {Promise<string>} The user's raw answer (untrimmed).
+ */
+export async function _promptForContinueWithMismatch(deps = {}) {
+  const createInterface =
+    deps.createInterface ||
+    (async () => {
+      const readline = await import('readline');
+      return readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      });
+    });
+
+  const rl = await createInterface();
+  try {
+    return await new Promise((resolve) => {
+      rl.question(
+        'Would you like to continue with unsupported Python version? (y/n): ',
+        resolve
+      );
+    });
+  } finally {
+    rl.close();
+  }
+}