@jrpool/kilotest 24.1.1 → 25.0.0

package/env.example

@@ -1,12 +1,23 @@
-# For a local development/test host, ENVIRONMENT=test.
-ENVIRONMENT=production
-# PROTOCOL must be http if a local dev/test host or reverse-proxied server, or otherwise https.
+# ENVIRONMENT=test for a dev/test host, =production for a deployed host.
+ENVIRONMENT=__placeholder__
+# PROTOCOL=http for a local dev/test host or reverse-proxied server, otherwise =https.
 PROTOCOL=__placeholder__
-# AUTH_CODE must be 3 characters long.
+# AUTH_CODE for manager operations; must be 3 characters long.
 AUTH_CODE=__placeholder__
+# Name of Testaro agent.
 TESTARO_AGENT=testaro-agent
-# TESTARO_AGENT_PW must be identical to NETWATCH_AUTH in the Testaro .env.
+# Testaro agent password (same as NETWATCH_AUTH in the Testaro .env.
 TESTARO_AGENT_PW=__placeholder__
+# Name of research agent (AI agent calling Kilotest as a tool).
+RESEARCH_AGENT=research-agent
+# Research agent password.
+RESEARCH_AGENT_PW=__placeholder__
+# URL of this Kilotest host.
+THIS_KILOTEST_HOST=__placeholder__
+# URL of a dev/test Kilotest host.
+LOCAL_KILOTEST_HOST=http://localhost:3000
+# URL of the deployed Kilotest host.
+DEPLOYED_KILOTEST_HOST=https://kilotest.com
 # Alert email configuration:
 MANAGER_EMAIL=__placeholder__
 ALERT_API_HOST=api.resend.com

package/index.js

@@ -67,30 +67,43 @@ const claimedPath = path.join(jobsPath, 'claimed');
 const failedPath = path.join(jobsPath, 'failed');
 const testaroAgent = process.env.TESTARO_AGENT;
 const testaroAgentPW = process.env.TESTARO_AGENT_PW;
+const researchAgent = process.env.RESEARCH_AGENT;
+const researchAgentPW = process.env.RESEARCH_AGENT_PW;
 // Values that may require alerts.
 const balancePath = path.join(__dirname, 'aiService0Balance.json');
 const WAVE_THRESHOLD = Number(process.env.WAVE_BALANCE_THRESHOLD);
 const AI_SERVICE0_THRESHOLD = Number(process.env.AI_SERVICE0_BALANCE_THRESHOLD);
 const AI_MODEL0_INPUT_PRICE = Number(process.env.AI_MODEL0_INPUT_PRICE);
 const AI_MODEL0_OUTPUT_PRICE = Number(process.env.AI_MODEL0_OUTPUT_PRICE);
+const researchAgents = {
+  'research-agent': 'Internal Research Agent'
+}
 
 // FUNCTIONS
 
-// Serves an error message.
+// Serves or sends an error message.
 const serveError = async (error, response, isHumanUser = true) => {
-  console.log(error.message);
+  console.log(error.message || 'ERROR');
   if (! response.writableEnded) {
     response.statusCode = 400;
+    // If the request is from a human user:
     if (isHumanUser) {
+      // Serve an HTML page containing the message property of the error.
       response.setHeader('content-type', 'text/html; charset=utf-8');
       const errorTemplate = await fs.readFile('error.html', 'utf8');
-      const errorPage = errorTemplate.replace(/__error__/, error.message);
+      const errorPage = errorTemplate.replace(/__error__/, error.message || 'ERROR');
       response.end(errorPage);
-    } else {
+    }
+    // Otherwise, i.e. if it is from an agent:
+    else {
+      // Send a JSON response containing the entire error.
       response.setHeader('content-type', 'application/json; charset=utf-8');
-      response.end(JSON.stringify({error: error.message}));
+      response.end(JSON.stringify({error}));
     }
   }
+  else {
+    console.log('Cannot send error response because the response has ended.');
+  }
 };
 // Checks a report for balances nearing exhaustion.
 const checkBalancesForAlerts = async report => {
@@ -107,7 +120,6 @@ const checkBalancesForAlerts = async report => {
         `Only ${creditsRemaining} WAVE credits remain (3 used per job)`
       );
     }
-    // AI service 0.
     const testaroAct = report.acts.find(act => act.type === 'test' && act.which === 'testaro');
     // Get the AI model token usage for the testaro allCaps test.
     const usage = testaroAct?.data?.ruleData?.allCaps?.aiModelUsage;
@@ -231,7 +243,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the request is syntactically invalid:
       else {
         // Report the error.
-        await serveError({message: 'Invalid report request'}, response, true);
+        await serveError({message: 'ERROR: Invalid report request'}, response, true);
       }
     }
     // Otherwise, if it is for an HTML page other than the home page:
@@ -258,7 +270,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the answer cannot be generated:
       else {
         // Report the error.
-        await serveError({message: 'Invalid request'}, response, true);
+        await serveError({message: 'ERROR: Invalid request'}, response, true);
       }
     }
     // Otherwise, if it is for a tutorial image:
@@ -274,7 +286,7 @@ const requestHandler = async (request, response) => {
         response.end(img);
       }
       catch (_) {
-        await serveError({message: 'Image not found'}, response, true);
+        await serveError({message: 'ERROR: Image not found'}, response, true);
       }
     }
     // Otherwise, if it is for the application icon:
@@ -340,7 +352,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the request is invalid:
       else {
         // Report the error.
-        await serveError({message: 'Invalid retest recommendation'}, response, true);
+        await serveError({message: 'ERROR: Invalid retest recommendation'}, response, true);
       }
     }
     // Otherwise, if it is a test recommendation:
@@ -368,7 +380,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the request is invalid:
       else {
         // Report the error.
-        await serveError({message: 'Invalid test recommendation'}, response, true);
+        await serveError({message: 'ERROR: Invalid test recommendation'}, response, true);
       }
     }
     // Otherwise, if it is an action on a test or retest recommendation:
@@ -416,7 +428,7 @@ const requestHandler = async (request, response) => {
       // Otherwise, i.e. if the request is invalid:
       else {
         // Report the error.
-        await serveError({message: 'Invalid test order'}, response, true);
+        await serveError({message: 'ERROR: Invalid test order'}, response, true);
       }
     }
     // Otherwise, if it is a reannotation order:
@@ -459,10 +471,11 @@ const requestHandler = async (request, response) => {
         await serveError({message: answerData.error}, response, true);
       }
     }
-    // Otherwise, if it is a request from a Testaro agent:
+    // Otherwise, if it is a request from an agent:
     else if (pageName === 'api') {
-      const [agentID, service] = pageArgs.split('/');
-      // If the agent is authorized:
+      // Get the agent ID, the service, and any service specifications from the path.
+      const [agentID, service, ... specs] = pageArgs.split('/');
+      // If the agent is the authorized Testaro instance and it is authenticated:
       if (agentID === testaroAgent && postData.agentPW === testaroAgentPW) {
         // If the service is job assignment:
         if (service === 'job') {
@@ -570,9 +583,43 @@ const requestHandler = async (request, response) => {
           );
         }
       }
-      // Otherwise, i.e. if the agent is not authorized:
+      // Otherwise, if the agent is the authorized research agent and it is authenticated:
+      else if (agentID === researchAgent && postData.agentPW === researchAgentPW) {
+        // If the service is provision of facts about issues in a report:
+        if (service === 'reportIssues') {
+          // Get the report identifiers from the path.
+          const [timeStamp, jobID] = specs;
+          const agentName = researchAgents[agentID];
+          const args = [agentName, timeStamp, jobID];
+          const reportSpecsBad = await isHidden(timeStamp, jobID);
+          // If the report is nonexistent or hidden:
+          if (reportSpecsBad) {
+            // Report this.
+            await serveError(
+              {message: reportSpecsBad === true ? 'Report nonexistent or hidden' : reportSpecsBad},
+              response,
+              false
+            );
+          }
+          // Otherwise, i.e. if the report is available:
+          else {
+            // Get the response (potentially error) data.
+            const responseData = await require(path.join(__dirname, 'reportIssues', 'api'))
+            .response(args);
+            // Send them.
+            response.end(JSON.stringify(responseData));
+          }
+        }
+        // Otherwise, i.e. if the service is invalid:
+        else {
+          // Report this.
+          await serveError({message: 'ERROR: Invalid service request'}, response, false);
+        }
+      }
+      // Otherwise, i.e. if the agent is not authorized or not authenticated:
       else {
-        await serveError({message: 'ERROR: Invalid Testaro agent'}, response, false);
+        // Report this.
+        await serveError({message: 'ERROR: Invalid agent'}, response, false);
       }
     }
     // Otherwise, if it is a tutorial comment:
@@ -617,6 +664,9 @@ const serve = async (protocolModule, options) => {
     console.log(`Kilotest server listening at ${protocol}://localhost:${port}.`);
   });
 };
+
+// EXECUTION
+
 if (protocol === 'http') {
   console.log('Starting HTTP server');
   serve(http, {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jrpool/kilotest",
-  "version": "24.1.1",
+  "version": "25.0.0",
   "description": "An ensemble testing service with a focus on accessibility",
   "main": "index.js",
   "scripts": {

package/reportIssues/api.js

@@ -1,231 +1,53 @@
 /*
-  index.js
-  Answers the report-issues question.
+  api.js
+  Responds to the report-issues request.
 */
 
 // IMPORTS
 
+const {getData, getToolData} = require('./util');
 const {
-  getPageDataStrings,
-  getReport,
+  getDateTime,
+  getNowStamp,
+  getRandomString,
   getToolNamesString,
-  getWCAGLink,
-  getWeightName,
-  htmlSafe,
   isHidden,
-  isValidReport,
-  objectSort,
   tools
 } = require('../util');
-const {issues} = require('testilo/procs/score/tic');
-const fs = require('fs/promises');
-const path = require('path');
 
 // FUNCTIONS
 
-// Gets data on the issues reported in a report.
-const getIssuesData = async (timeStamp, jobID) => {
-  // Get the report.
-  const report = await getReport(timeStamp, jobID);
-  // If it is valid:
-  if (typeof report === 'object' && isValidReport(report)) {
-    const issuesData = {
-      reporters: new Set(),
-      reporterCount: 0,
-      reportersString: '',
-      violators: new Set(),
-      violatorCount: 0,
-      preventions: {},
-      issuesObject: {},
-      issueCount: 0,
-      issues: []
+// Gets facts about tools.
+const getToolFacts = toolIDs => {
+  const crypticData = getToolData(toolIDs);
+  return crypticData.map(tool => {
+    const {toolID, toolName, toolMaker} = tool;
+    return {
+      identifier: toolID,
+      name: toolName,
+      sponsor: toolMaker
     };
-    const {issuesObject, reporters, violators} = issuesData;
-    // For each act in it:
-    report.acts.forEach(act => {
-      // If it is a test act:
-      if (act.type === 'test') {
-        const {result, which} = act;
-        const instances = result?.standardResult?.instances ?? [];
-        // For each of its standard instances:
-        instances.forEach(instance => {
-          const {issueID} = instance;
-          // If the instance has a non-ignorable classified issue:
-          if (issueID && issues[issueID] && issueID !== 'ignorable') {
-            // Ensure that the issues data include data on the issue.
-            issuesObject[issueID] ??= {
-              issueID,
-              weight: issues[issueID].weight ?? 0,
-              reporters: new Set(),
-              reporterCount: 0,
-              reportersString: '',
-              violators: new Set(),
-              violatorCount: 0
-            };
-            // Ensure that the tool is in the issues data.
-            reporters.add(which);
-            // Ensure that it is in the issue data.
-            issuesObject[issueID].reporters.add(which);
-            const {catalogIndex} = instance;
-            // If the instance has a catalog index:
-            if (catalogIndex) {
-              // Ensure that the violator is in the issues data.
-              violators.add(catalogIndex);
-              // Ensure that it is in the issue data.
-              issuesObject[issueID].violators.add(catalogIndex);
-            }
-          }
-        });
-      }
-    });
-    // Populate the unpopulated subproperties of the issues data.
-    issuesData.reporterCount = issuesData.reporters.size;
-    issuesData.reportersString = getToolNamesString(issuesData.reporters);
-    issuesData.violatorCount = issuesData.violators.size;
-    issuesData.preventions = report.jobData.preventions;
-    issuesData.issueCount = Object.keys(issuesData.issuesObject).length;
-    issuesData.issues = Object.values(issuesData.issuesObject);
-    // For each issue in the issues data:
-    issuesData.issues.forEach(issue => {
-      // Populate its unpopulated properties.
-      issue.reporterCount = issue.reporters.size;
-      issue.reportersString = getToolNamesString(issue.reporters);
-      issue.violatorCount = issue.violators.size;
-    });
-    // Sort the issues alphabetically by reporters string.
-    objectSort(issuesData.issues, 'reportersString', 'alpha');
-    // Sort the issues again in descending reporter-count order, making this the primary order.
-    objectSort(issuesData.issues, 'reporterCount', 'numericDown');
-    // Return the issues data.
-    return issuesData;
-  }
-};
-// Adds parameters to a query for the answer page.
-const populateQuery = async (timeStamp, jobID, query) => {
-  // Get fact descriptions for the report.
-  const pageDataStrings = await getPageDataStrings(timeStamp, jobID);
-  const {what, urlLink, testInfo} = pageDataStrings;
-  const issuesData = await getIssuesData(timeStamp, jobID);
-  // If this failed:
-  if (typeof issuesData === 'string') {
-    // Return this.
-    return issuesData;
-  }
-  const {
-    issueCount,
-    preventions,
-    reporterCount,
-    reportersString,
-    violatorCount
-  } = issuesData;
-  // Add an issue count description to the query.
-  query.issueCount = issueCount === 1 ? '1 issue was' : `${issueCount} issues were`;
-  query.reporterCount = reporterCount === 1 ? '1 tool' : `${reporterCount} tools`;
-  // Add a reporter count and list to the query.
-  query.reporters = reportersString;
-  // Add a violator count to the query.
-  query.violatorCount = violatorCount === 1 ? '1 violator was' : `${violatorCount} violators were`;
-  // Add page data to the query.
-  query.target = what;
-  query.urlLink = urlLink;
-  query.testInfo = testInfo;
-  query.timeStamp = timeStamp;
-  query.jobID = jobID;
-  const preventionStrings = [];
-  const margin = ' '.repeat(6);
-  Object.keys(preventions).forEach(preventedToolID => {
-    const toolName = tools[preventedToolID];
-    const toolNameString = `${toolName[0]} (${toolName[1]})`;
-    const causeString = htmlSafe(preventions[preventedToolID]);
-    const preventionString = `${margin}<li>Page not testable by ${toolNameString}: ${causeString}</li>`;
-    preventionStrings.push(preventionString);
-  });
-  query.preventions = preventionStrings.join('\n');
-  // For each weight:
-  [4, 3, 2, 1].forEach(weight => {
-    // Initialize data on issues having the weight.
-    const weightData = [];
-    // Initialize the lines for the weight.
-    const weightLines = [];
-    // For each issue:
-    issuesData.issues.forEach(issueData => {
-      const {
-        issueID, reporterCount, reportersString, violatorCount, weight: issueWeight
-      } = issueData;
-      // If it has the weight:
-      if (issueWeight === weight) {
-        const issue = issues[issueID];
-        const {wcag, why} = issue;
-        const wcagLink = `<a href="${getWCAGLink(wcag)}">${wcag}</a>`;
-        // Add data on it to the weight data.
-        weightData.push({
-          issueID,
-          summary: issue.summary,
-          why,
-          wcag: wcagLink,
-          reporterCount,
-          reportersString,
-          violatorCount
-        });
-      }
-    });
-    const weightName = getWeightName(weight);
-    // Add the issue count to the query.
-    query[`${weightName}Count`] = weightData.length;
-    // If any reported issues have the weight:
-    if (weightData.length) {
-      // Add the start of a list of the issues with the weight to the lines.
-      weightLines.push(`${margin}<ul class="headed">`);
-      // For each issue with the weight:
-      weightData.forEach(weightIssue => {
-        const {issueID, reporterCount, reportersString, violatorCount, wcag, why} = weightIssue;
-        // Add the start of a list item to the lines.
-        weightLines.push(`${margin}  <li>`);
-        // Add a heading summarizing the issue to the lines.
-        weightLines.push(`${margin}    <h5>${weightIssue.summary}</h5>`);
-        // Add the start of alist of facts about the issue to the lines.
-        weightLines.push(`${margin}    <ul class="pseudoTopLevel">`);
-        // Add the issue facts to the lines.
-        weightLines.push(`${margin}      <li>Why it matters: ${why}`);
-        weightLines.push(`${margin}      <li>Related WCAG standard: ${wcag}`);
-        const reporterCountString = reporterCount === 1 ? '1 tool' : `${reporterCount} tools`;
-        weightLines.push(
-          `${margin}      <li>Reported by ${reporterCountString} (${reportersString})</li>`
-        );
-        const violatorCountString = violatorCount === 1
-        ? '1 violator was'
-        : `${violatorCount} violators were`;
-        weightLines.push(`${margin}      <li>${violatorCountString} reported</li>`);
-        // Add the end of the fact list to the lines.
-        weightLines.push(`${margin}    </ul>`);
-        // Add the start of a link list to the lines.
-        weightLines.push(`${margin}    <ul class="nav">`);
-        const whereQuestionString = 'Where was the issue found?';
-        const labelString = `Where was the ${weightIssue.summary} issue found on the ${what} page?`;
-        const href = `href="/reportIssue.html/${issueID}/${timeStamp}/${jobID}"`;
-        const label = `aria-label="${labelString}"`;
-        const whereLink = `<a ${href} ${label}>${whereQuestionString}</a>`;
-        // Add a violations link to the lines.
-        weightLines.push(`${margin}      <li>${whereLink}</li>`);
-        // Add the end of the link list to the lines.
-        weightLines.push(`${margin}    </ul>`);
-        // Add the end of the list item to the lines.
-        weightLines.push(`${margin}  </li>`);
-      });
-      // Add the end of the list of issues with the weight to the lines.
-      weightLines.push(`${margin}</ul>`);
-      // Add the lines documenting the issues with the weight to the query.
-      query[`${weightName}Details`] = weightLines.join('\n');
-    }
-    // Otherwise, i.e. if no reported issues have the weight:
-    else {
-      query[`${weightName}Details`] = `${margin}  <p>None</p>`;
-    }
   });
 };
-// Returns a page answering the target-issues question.
-exports.answer = async pageArgs => {
-  const [timeStamp, jobID] = pageArgs.split('/');
+// Gets facts about an issue.
+const getIssueFacts = issue => {
+  const {issueID, reporterCount, reporterList, reporters, summary, violatorCount, wcag, why} = issue;
+  return {
+    identifier: issueID,
+    summary,
+    'related WCAG principle (n.n) or success criterion (n.n.n)': wcag,
+    'impact on a user': why,
+    'tools reporting violations of rules belonging to the issue': {
+      'number of the tools': reporterCount,
+      'alphabetized list of names of the tools': reporterList,
+      'facts about the tools alphabetized by name': getToolFacts(reporters.map(tool => tool.toolID))
+    },
+    'number of HTML elements reported as exhibiting the issue': violatorCount
+  };
+};
+// Returns a response to a target-issues request.
+exports.response = async args => {
+  const [agentName, timeStamp, jobID] = args;
   const reportIsHidden = await isHidden(timeStamp, jobID);
   // If the report is not available:
   if (reportIsHidden) {
@@ -234,26 +56,63 @@ exports.answer = async pageArgs => {
       message: 'Report not available'
     };
   }
-  const query = {};
-  // Create a query to replace the placeholders.
-  await populateQuery(timeStamp, jobID, query);
-  // If the report facts were obtained:
-  if (query.testInfo) {
-    // Get the template.
-    let answerPage = await fs.readFile(path.join(__dirname, 'index.html'), 'utf8');
-    // Replace its placeholders.
-    Object.keys(query).forEach(param => {
-      answerPage = answerPage.replace(new RegExp(`__${param}__`, 'g'), query[param]);
-    });
-    // Return the populated page.
-    return {
-      status: 'ok',
-      answerPage
-    };
-  }
-  // Otherwise, i.e. if they were not obtained, report this.
-  return {
-    status: 'error',
-    error: 'Report processing failed'
+  // Otherwise, i.e. if the report is available, get data on the target and issues.
+  const data = await getData(timeStamp, jobID);
+  const {pageData, issuesData} = data;
+  const {what, url, daysAgo} = pageData;
+  const {issueCount, issues, preventions, reporterCount, reporters, violatorCount} = issuesData;
+  const preventedTools = getToolFacts(Object.keys(preventions));
+  preventedTools.forEach(preventedTool => {
+    preventedTool['reason for failure'] = preventions[preventedTool.identifier];
+  });
+  const thisHost = process.env.THIS_KILOTEST_HOST;
+  // Get a response.
+  const response = {
+    summary: `This document fulfills a request made by an agent to Kilotest. The agent requested data from a report produced by Kilotest. The report contains results of tests performed on a web page by an ensemble of tools. The tools use a combination of rule-based and machine-learning-based methods to identify accessibility, usability, and standard-conformity issues. More detailed information about Kilotest is available from its deployed instance, ${process.env.DEPLOYED_KILOTEST_HOST}. which contains an introduction on its home page and a tutorial.`,
+    'tool name': 'Kilotest',
+    request: {
+      'name of requesting agent': agentName,
+      'type of request': {
+        identifier: 'reportIssues',
+        description: 'What issues did Kilotest report in the specified report?'
+      }
+    },
+    'response metadata': {
+      'date and time': new Date().toISOString(),
+      'identifier': `${getNowStamp()}-${getRandomString(3)}`
+    },
+    report: {
+      identifier: `${timeStamp}-${jobID}`,
+      'creation date': getDateTime(timeStamp),
+      'days since the creation date': daysAgo,
+      'URL for human inspection': `${thisHost}/reportIssues.html/${timeStamp}/${jobID}`
+    },
+    'tested web page': {
+      description: what,
+      URL: url
+    },
+    'names of tools that tried to test the page': getToolNamesString(Object.keys(tools)),
+    'tools that were unable to test the page': preventedTools,
+    'tools that reported issues': {
+      'number of tools': reporterCount,
+      'facts about the tools': getToolFacts(reporters.map(tool => tool.toolID))
+    },
+    'number of issues reported': {
+      'total': issueCount,
+      'by priority': {
+        'highest priority': issues[4].length,
+        'high priority': issues[3].length,
+        'low priority': issues[2].length,
+        'lowest priority': issues[1].length
+      }
+    },
+    'number of HTML elements reported as exhibiting issues': violatorCount,
+    'issues reported': {
+      'highest priority': issues[4].map(issue => getIssueFacts(issue)),
+      'high priority': issues[3].map(issue => getIssueFacts(issue)),
+      'low priority': issues[2].map(issue => getIssueFacts(issue)),
+      'lowest priority': issues[1].map(issue => getIssueFacts(issue))
+    }
   };
+  return response;
 };

package/reportIssues/index.js

@@ -14,7 +14,6 @@ const {
   isHidden,
   tools
 } = require('../util');
-const {issues} = require('testilo/procs/score/tic');
 const fs = require('fs/promises');
 const path = require('path');
 
@@ -22,7 +21,7 @@ const path = require('path');
 
 // Adds parameters to a query for the answer page.
 const populateQuery = async (timeStamp, jobID, query) => {
-  // Get data on the page and its issues according to the report.
+  // Get data on the target and its issues according to the report.
   const data = await getData(timeStamp, jobID);
   const {pageData, issuesData} = data;
   // If the page data are invalid:
@@ -35,10 +34,10 @@ const populateQuery = async (timeStamp, jobID, query) => {
     // Return this.
     return issuesData;
   }
-  // Otherwise, get fact descriptions for the page.
+  // Otherwise, get fact descriptions for the target.
   const pageInfo = await getPageDataStrings(timeStamp, jobID, pageData);
   const {what, urlLink, testInfo} = pageInfo;
-  // Add page data to the query.
+  // Add target data to the query.
   query.target = what;
   query.urlLink = urlLink;
   query.testInfo = testInfo;

package/reportIssues/util.js

@@ -11,7 +11,7 @@ const issuesClassification = require('testilo/procs/score/tic').issues;
 // FUNCTIONS
 
 // Converts tool IDs to tool data sorted by tool name.
-const getToolData = toolIDs => objectSort(
+const getToolData = exports.getToolData = toolIDs => objectSort(
   Array.from(toolIDs).map(toolID => {
     const toolData = tools[toolID];
     return {
@@ -47,12 +47,6 @@ const getIssuesData = async (timeStamp, jobID) => {
       reporterCount: 0,
       violatorCount: 0,
       preventions: report.jobData.preventions,
-      priorityNames: {
-        4: 'highest',
-        3: 'high',
-        2: 'low',
-        1: 'lowest'
-      },
       issues: {
         4: [],
         3: [],

package/researchAgent.js

@@ -0,0 +1,95 @@
+/*
+  © 2026 Jonathan Robert Pool.
+
+  Licensed under the MIT License. See LICENSE file at the project root or
+  https://opensource.org/license/mit/ for details.
+
+  SPDX-License-Identifier: MIT
+*/
+
+/*
+  researchAgent.js
+  Module for simulating a research agent.
+*/
+
+// IMPORTS
+
+const {getLogs} = require('./util');
+require('dotenv').config();
+const httpClient = require('http');
+const httpsClient = require('https');
+
+// CONSTANTS
+
+const agent = process.env.RESEARCH_AGENT;
+const agentPW = process.env.RESEARCH_AGENT_PW;
+const kilotestHosts = [process.env.LOCAL_KILOTEST_HOST, process.env.DEPLOYED_KILOTEST_HOST];
+// Randomly chosen Kilotest host.
+const kilotestHost = kilotestHosts[Math.random() < 0.5 ? 0 : 1];
+const hostParts = kilotestHost.split(/:\/*/);
+const scheme = hostParts[0];
+const host = hostParts[1];
+const port = hostParts[2] || (scheme === 'https' ? 443 : 80);
+const services = ['reportIssues'];
+// Randomly chosen service.
+const service = services[Math.floor(services.length * Math.random())];
+
+// FUNCTIONS
+
+// Submits a random research request to a random Kilotest host.
+const requestService = async () => {
+  const logs = await getLogs();
+  // Randomly chosen log.
+  const log = logs[Math.floor(logs.length * Math.random())];
+  const specs = log.jobName.split('-').join('/');
+  const path = `/api/${agent}/${service}/${specs}`;
+  const client = scheme === 'https' ? httpsClient : httpClient;
+  // Use its job name in the request path.
+  const requestOptions = {
+    method: 'POST',
+    host,
+    port,
+    path,
+    headers: {
+      'content-type': 'application/json; charset=utf-8'
+    }
+  };
+  console.log(`About to submit ${scheme} request as JSON on port ${port} to ${host}${path}`);
+  // Submit a request.
+  client.request(requestOptions, response => {
+    // Initialize a collection of data from the response.
+    const chunks = [];
+    response
+    // If the response throws an error:
+    .on('error', async error => {
+      // Report it.
+      console.log(error.message);
+    })
+    // If the response delivers data:
+    .on('data', chunk => {
+      // Add them to the collection.
+      chunks.push(chunk);
+    })
+    // When the response is completed:
+    .on('end', async () => {
+      const content = chunks.join('');
+      // Output it.
+      try {
+        console.log(JSON.stringify(JSON.parse(content), null, 2));
+      }
+      catch (error) {
+        console.log(error.message);
+        console.log(`Response content: ${content || 'No content'}`);
+      }
+    });
+  })
+  // Finish sending the job request.
+  .end(JSON.stringify({
+    agentPW
+  }));
+};
+
+// EXECUTION
+
+// Execute the research agent.
+requestService();

package/testOrder/index.js

@@ -5,7 +5,7 @@
 
 // IMPORTS
 
-const {getJSON, getNowStamp, getRecs, isURL} = require('../util');
+const {getJSON, getNowStamp, getRandomString, getRecs, isURL} = require('../util');
 const fs = require('fs/promises');
 const path = require('path');
 
@@ -20,7 +20,7 @@ exports.answer = async (url, what, authCode) => {
     const job = JSON.parse(jobTemplateJSON);
     const nowStamp = getNowStamp();
     // Populate the template with job properties.
-    const jobIDSuffix = Date.now().toString(36).slice(5);
+    const jobIDSuffix = getRandomString(3);
     const jobName = `${nowStamp}-${jobIDSuffix}`;
     job.id = jobName;
     job.creationTimeStamp = nowStamp;

package/util.js

@@ -40,6 +40,10 @@ const tools = exports.tools = {
 
 // FUNCTIONS
 
+// Returns a random string.
+exports.getRandomString = length => {
+  return Math.random().toString(36).slice(2, length + 2);
+};
 // Returns whether a report is valid.
 exports.isValidReport = report => {
   // Return whether it has the type and properties required by Kilotest:
@@ -114,7 +118,7 @@ const getDateString = exports.getDateString = timeStamp => {
   return '';
 };
 // Returns the date and time represented by a time stamp.
-const getDateTime = timeStamp => {
+const getDateTime = exports.getDateTime = timeStamp => {
   const dateString
   = `20${timeStamp.slice(0, 2)}-${timeStamp.slice(2, 4)}-${timeStamp.slice(4,6)}T${timeStamp.slice(7,9)}:${timeStamp.slice(9,11)}Z`;
   const dateTime = new Date(dateString);
@@ -484,7 +488,7 @@ exports.getTextFragmentHref = (text, url) => {
   // Return a text-fragment link.
   return `${url}#:~:text=${fragmentList}`;
 };
-// Returns an array of the logs of the public reports on the tested targets.
+// Returns an array of the logs, with job names added, of the non-hidden reports.
 exports.getLogs = async () => {
   // Initialize data on the tested targets.
   const logs = [];