@jrpool/kilotest 55.0.0 → 57.1.0

package/api/requestRetest.ts

@@ -6,7 +6,7 @@
 // IMPORTS
 
 import {z} from 'zod';
-import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {buildRequestDisposition, getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
 import {checkLength, isJobID, isTimeStamp, processTestRequest} from '../util.ts';
 import {requestRetestResponseSchema} from './schemas.ts';
 
@@ -60,38 +60,15 @@ export const response = async (args: string[]) => {
         'reason why the page should be retested': reason
       };
       // Add information about the disposition of the request.
-      if (requestResult === 'ok') {
-        requestDisposition = {
-          'what happens next': 'Your request is likely to be approved and processed within 1 hour to 1 day.',
-          'how you can check for completion': 'You can call the listReports tool to learn whether the page has been retested and a new report is available.',
-          'how a web user can check for completion': `A web user can visit ${thisHost}/listReports.html to learn whether the page has been retested and a new report is available.`
-        };
-      }
-      else {
-        const failureFact = 'Your request will not be processed, because ';
-        let failureReason: string;
-        if (requestResult === 'description') {
-          failureReason = 'a request to test a page with the same description is already approved.'
-        }
-        else if (requestResult === 'url') {
-          failureReason = 'a request to test a page with the same URL is already approved.'
-        }
-        else if (requestResult === 'superseded') {
-          failureReason = 'a later report about a page with the same description is available.'
-        }
-        else if (requestResult === 'queueFull') {
-          failureReason = 'too many requests are awaiting approval right now. Please try again later, ' +
-            'or post your request at https://github.com/jrpool/kilotest/issues or email info@kilotest.com.'
-        }
-        else {
-          failureReason = 'an identical request is already awaiting approval.'
-        }
-        requestDisposition = {
-          'what happens next': `${failureFact}${failureReason}`,
-          'how you can check for completion': 'Not applicable.',
-          'how a web user can check for completion': 'Not applicable.'
-        }
-      }
+      requestDisposition = buildRequestDisposition(
+        requestResult,
+        {
+          whatHappensNext: 'Your request is likely to be approved and processed within 1 hour to 1 day.',
+          howToCheck: 'You can call the listReports tool to learn whether the page has been retested and a new report is available.',
+          howWebUserChecks: `A web user can visit ${thisHost}/listReports.html to learn whether the page has been retested and a new report is available.`
+        },
+        {result: 'superseded', reason: 'a later report about a page with the same description is available.'}
+      );
     }
   }
   // Create the response content.

package/api/routes.test.ts

@@ -11,22 +11,25 @@ import {routes} from './routes.ts';
 
 // TESTS
 
-test('routes exports an array with 8 operations', () => {
+test('routes exports an array with 11 operations', () => {
   assert.ok(Array.isArray(routes));
-  assert.equal(routes.length, 8);
+  assert.equal(routes.length, 11);
 });
 
 test('routes includes all expected operation IDs', () => {
   const ids = routes.map(r => r.operationId).sort();
   assert.deepEqual(ids, [
+    'awaitTest',
     'getReport',
     'listDiagnoses',
     'listIssues',
     'listReports',
     'listViolators',
+    'orderNewTest',
+    'orderRetest',
     'requestFeature',
-    'requestRetest',
-    'requestTest'
+    'requestNewTest',
+    'requestRetest'
   ]);
 });
 

package/api/routes.ts

@@ -11,17 +11,23 @@ import {
   listViolatorsSchema,
   listDiagnosesSchema,
   getReportSchema,
-  requestTestSchema,
+  requestNewTestSchema,
   requestRetestSchema,
   requestFeatureSchema,
+  orderNewTestSchema,
+  orderRetestSchema,
+  awaitTestSchema,
   listReportsResponseSchema,
   listIssuesResponseSchema,
   listViolatorsResponseSchema,
   listDiagnosesResponseSchema,
   getReportResponseSchema,
-  requestTestResponseSchema,
+  requestNewTestResponseSchema,
   requestRetestResponseSchema,
-  requestFeatureResponseSchema
+  requestFeatureResponseSchema,
+  orderNewTestResponseSchema,
+  orderRetestResponseSchema,
+  awaitTestResponseSchema
 } from './schemas.ts';
 
 // ROUTES
@@ -67,12 +73,12 @@ export const routes = [
     responseSchema: getReportResponseSchema
   },
   {
-    operationId: 'requestTest',
+    operationId: 'requestNewTest',
     method: 'post',
-    path: '/api/requestTest',
+    path: '/api/requestNewTest',
     summary: 'Request that a page be tested',
-    bodySchema: z.object(requestTestSchema),
-    responseSchema: requestTestResponseSchema
+    bodySchema: z.object(requestNewTestSchema),
+    responseSchema: requestNewTestResponseSchema
   },
   {
     operationId: 'requestRetest',
@@ -93,5 +99,37 @@ export const routes = [
     summary: 'Request a feature improvement or new feature',
     bodySchema: z.object(requestFeatureSchema),
     responseSchema: requestFeatureResponseSchema
+  },
+  {
+    operationId: 'orderNewTest',
+    method: 'post',
+    path: '/api/orderNewTest',
+    summary: 'Order that a page be tested immediately, without manual approval',
+    bodySchema: z.object(orderNewTestSchema),
+    responseSchema: orderNewTestResponseSchema
+  },
+  {
+    operationId: 'orderRetest',
+    method: 'post',
+    path: '/api/orderRetest/{timeStamp}/{jobID}',
+    summary: 'Order that a page be retested immediately, without manual approval',
+    pathParamsSchema: z.object({
+      timeStamp: orderRetestSchema.timeStamp,
+      jobID: orderRetestSchema.jobID
+    }),
+    bodySchema: z.object({reason: orderRetestSchema.reason}),
+    responseSchema: orderRetestResponseSchema
+  },
+  {
+    operationId: 'awaitTest',
+    method: 'post',
+    path: '/api/awaitTest/{timeStamp}/{jobID}',
+    summary: 'Wait for a job ordered via orderNewTest or orderRetest to complete',
+    pathParamsSchema: z.object(awaitTestSchema),
+    // No caller-supplied fields beyond the path parameters; an empty body schema (rather
+    // than omitting bodySchema) keeps this route consistent with the "every POST route
+    // has a bodySchema" invariant the rest of this table and its own test maintain.
+    bodySchema: z.object({}),
+    responseSchema: awaitTestResponseSchema
   }
 ];

package/api/schemas.ts

@@ -41,8 +41,8 @@ export const getReportSchema = {
   jobID: z.string().describe('Job identifier of the report (example: x9z)')
 };
 
-// requestTest: POST /api/requestTest
-export const requestTestSchema = {
+// requestNewTest: POST /api/requestNewTest
+export const requestNewTestSchema = {
   description: z.string().describe('1- to 100-character description of the page conforming to the naming convention used in the listReports output'),
   URL: z.string().describe('12- to 300-character URL of the page, including the https:// scheme and any query'),
   reason: z.string().describe('20- to 100-character reason why the page should be tested')
@@ -60,6 +60,26 @@ export const requestFeatureSchema = {
   feature: z.string().describe('20- to 1000-character description of requested feature improvement or new feature')
 };
 
+// orderNewTest: POST /api/orderNewTest
+export const orderNewTestSchema = {
+  description: z.string().describe('1- to 100-character description of the page conforming to the naming convention used in the listReports output'),
+  URL: z.string().describe('12- to 300-character URL of the page, including the https:// scheme and any query'),
+  reason: z.string().describe('20- to 100-character reason why the page should be tested')
+};
+
+// orderRetest: POST /api/orderRetest/{timeStamp}/{jobID}
+export const orderRetestSchema = {
+  timeStamp: z.string().describe('Timestamp of the latest report about the page in YYMMDDTHHmm format (example: 260503T0432)'),
+  jobID: z.string().describe('Job identifier of the latest report about the page (example: x9z)'),
+  reason: z.string().describe('20- to 100-character reason why the page should be retested')
+};
+
+// awaitTest: POST /api/awaitTest
+export const awaitTestSchema = {
+  timeStamp: z.string().describe('Timestamp of the ordered job, from the report identifier returned by orderNewTest, in YYMMDDTHHmm format (example: 260503T0432)'),
+  jobID: z.string().describe('Job identifier of the ordered job, from the report identifier returned by orderNewTest (example: x9z)')
+};
+
 // listReports takes no input; omitted (mcp.ts already uses inputSchema: {}).
 
 // RESPONSE SCHEMAS
@@ -93,32 +113,40 @@ const toolsFactsSchema = z.object({
   'web users can obtain similar functionalities at': z.string()
 }).meta({id: 'ToolsFacts'});
 
-// Identifies a related request (e.g., the closest ancestor request in the drill-down hierarchy).
+// Identifies a related request (e.g., the closest ancestor request in the drill-down
+// hierarchy). method is usually GET (every drill-down tool's ancestor is a read), except
+// for orderNewTest/orderRetest, whose own ancestor is a GET, and awaitTest, whose ancestors
+// (orderNewTest and orderRetest) are both POST (they create a job).
 const requestReferenceSchema = z.object({
   'tool name': z.string(),
   description: z.string(),
-  method: z.literal('GET'),
+  method: z.enum(['GET', 'POST']),
   URL: z.string()
 }).meta({id: 'RequestReference'});
 
 // GET endpoints have no 'body'; POST endpoints get a request-specific body schema.
-const thisRequestSchema = (method: string, bodySchema?: ZodTypeAny) => z.object({
+// ancestorSchema overrides the default single-ancestor shape for a tool whose closest
+// ancestor is not unique: awaitTest can be reached from either orderNewTest or orderRetest,
+// and the identifier alone does not say which, so it reports both as an array rather
+// than arbitrarily picking one.
+const thisRequestSchema = (method: string, bodySchema?: ZodTypeAny, ancestorSchema: ZodTypeAny = requestReferenceSchema.nullable()) => z.object({
   description: z.string(),
   method: z.literal(method),
   URL: z.string(),
   ...(bodySchema ? {body: bodySchema} : {}),
-  'closest ancestor request': requestReferenceSchema.nullable()
+  'closest ancestor request': ancestorSchema
 });
 
 const envelope = <T extends ZodTypeAny>(
   method: string,
   responseContentSchema: T,
   bodySchema?: ZodTypeAny,
-  similarWebSchema: ZodTypeAny = similarWebRequestsSchema
+  similarWebSchema: ZodTypeAny = similarWebRequestsSchema,
+  ancestorSchema?: ZodTypeAny
 ) => z.object({
   'tool collection': toolsFactsSchema,
   'tool name': z.string(),
-  'this request': thisRequestSchema(method, bodySchema),
+  'this request': thisRequestSchema(method, bodySchema, ancestorSchema),
   'URLs of similar requests for web users': similarWebSchema,
   'response metadata': responseMetadataSchema,
   'response content': responseContentSchema
@@ -268,7 +296,7 @@ export const getReportResponseSchema = envelope('GET', z.object({
   'full report': z.unknown().describe('The full raw Testaro/Testilo report JSON, copied verbatim, or an error object if it could not be retrieved.')
 }));
 
-export const requestTestResponseSchema = envelope(
+export const requestNewTestResponseSchema = envelope(
   'POST',
   z.object({
     'details about your request': z.union([
@@ -285,7 +313,7 @@ export const requestTestResponseSchema = envelope(
       'how a web user can check for completion': z.string()
     }).nullable()
   }),
-  z.object(requestTestSchema)
+  z.object(requestNewTestSchema)
 );
 
 export const requestRetestResponseSchema = envelope(
@@ -320,3 +348,85 @@ export const requestFeatureResponseSchema = envelope(
   z.object(requestFeatureSchema),
   z.null()
 );
+
+// Identifies the report a successfully ordered or awaited job will produce, once complete.
+const reportIdentifierSchema = z.object({
+  timeStamp: z.string().describe('Timestamp to pass to listIssues once the report is ready.'),
+  jobID: z.string().describe('Job identifier to pass to listIssues once the report is ready.')
+}).meta({id: 'ReportIdentifier'});
+
+export const orderNewTestResponseSchema = envelope(
+  'POST',
+  z.object({
+    'details about your order': z.union([
+      z.object({error: z.string()}),
+      z.object({
+        'date and time received': z.string(),
+        'page to be tested': z.object({description: z.string(), URL: z.string()}),
+        'reason why the page should be tested': z.string()
+      })
+    ]),
+    'disposition of your order': z.object({
+      'what happens next': z.string(),
+      'report identifier': reportIdentifierSchema.nullable(),
+      'how you can check for completion': z.string(),
+      'do you want to wait for completion': z.string()
+    }).nullable()
+  }),
+  z.object(orderNewTestSchema),
+  z.object({
+    'this request': z.null(),
+    'closest ancestor request': z.string().nullable()
+  })
+);
+
+export const orderRetestResponseSchema = envelope(
+  'POST',
+  z.object({
+    'details about your order': z.union([
+      z.object({error: z.string()}),
+      z.object({
+        'date and time received': z.string(),
+        'page to be retested': z.object({description: z.string(), URL: z.string()}),
+        'reason why the page should be retested': z.string()
+      })
+    ]),
+    'disposition of your order': z.object({
+      'what happens next': z.string(),
+      'report identifier': reportIdentifierSchema.nullable(),
+      'how you can check for completion': z.string(),
+      'do you want to wait for completion': z.string()
+    }).nullable()
+  }),
+  z.object({reason: orderRetestSchema.reason}),
+  z.object({
+    'this request': z.null(),
+    'closest ancestor request': z.string().nullable()
+  })
+);
+
+export const awaitTestResponseSchema = envelope(
+  'POST',
+  z.object({
+    'details about your wait': z.union([
+      z.object({error: z.string()}),
+      z.object({
+        'report identifier': reportIdentifierSchema
+      })
+    ]),
+    'disposition of your wait': z.object({
+      outcome: z.enum(['completed', 'failed', 'timedOut']),
+      'what happened': z.string(),
+      'how you can check for completion': z.string()
+    }).nullable()
+  }),
+  undefined,
+  z.object({
+    'this request': z.null(),
+    'closest ancestor request': z.null()
+  }),
+  // awaitTest can be reached from either orderNewTest or orderRetest, and its own
+  // parameters (timeStamp/jobID) do not say which one produced them, so both possible
+  // ancestors are reported, rather than arbitrarily naming just one as "the" ancestor.
+  z.array(requestReferenceSchema).length(2)
+);

package/api/util.ts

@@ -15,7 +15,7 @@ import {
   objectSort,
   ruleEngines
 } from '../util.ts';
-import type {ReportExtract} from '../util.ts';
+import type {ReportExtract, TestRequestResult} from '../util.ts';
 import {issues as issueSpecs} from 'testaro-issues';
 
 // TYPES
@@ -29,6 +29,15 @@ export type ReportBasics = {
   'whether a later report about the same page exists': boolean;
 };
 
+// The disposition of a test/retest/instant-test request, as returned by
+// buildRequestDisposition, or null when the request itself was invalid (in which case
+// details about your request already carries the error, and no disposition applies).
+export type RequestDisposition = {
+  'what happens next': string;
+  'how you can check for completion': string;
+  'how a web user can check for completion': string;
+} | null;
+
 // FUNCTIONS
 
 // Returns the base URL of this Kilotest host.
@@ -50,7 +59,7 @@ export const getToolsFacts = () => ({
       'level 4': 'Use the listDiagnoses tool to get a list of diagnoses of how one element on one page exhibited one issue in one report.',
     },
     'how to generate more findings': {
-      'new testing': 'If no report is available yet about a page, use the requestTest tool to request that it be tested.',
+      'new testing': 'If no report is available yet about a page, use the requestNewTest tool to request that it be tested.',
       'retesting': 'If the listIssues tool shows that the latest report about a page is obsolete, because the page has been revised or for another reason, use the requestRetest tool to request that the page be retested.',
       'latency': 'Requests for testing and retesting are usually approved and fulfilled within one day.',
       'confirmation': 'Use the listReports tool to determine whether a requested new report exists. There is currently no process for notification of the outcome of requests.'
@@ -59,6 +68,54 @@ export const getToolsFacts = () => ({
   'URL': `${getThisHost()}/mcp`,
   'web users can obtain similar functionalities at': getThisHost()
 });
+// Returns the human-readable reason a test/retest/instant-test request was not
+// processed, given the result processTestRequest returned. requestResult is always a
+// rejection reason here ('description', 'url', 'queueFull', or an unrecognized value
+// meaning 'duplicate'); callers pass their own extra branch for a requestResult value
+// specific to their own request type ('reportExists' for requestNewTest, 'superseded' for
+// requestRetest), since that is the one branch not shared between them.
+export const getRequestFailureReason = (
+  requestResult: Exclude<TestRequestResult, 'ok'>,
+  extraBranch?: {result: TestRequestResult; reason: string}
+): string => {
+  if (requestResult === 'description') {
+    return 'a request to test a page with the same description is already approved.';
+  }
+  if (requestResult === 'url') {
+    return 'a request to test a page with the same URL is already approved.';
+  }
+  if (extraBranch && requestResult === extraBranch.result) {
+    return extraBranch.reason;
+  }
+  if (requestResult === 'queueFull') {
+    return 'too many requests are awaiting approval right now. Please try again later, ' +
+      'or post your request at https://github.com/jrpool/kilotest/issues or email info@kilotest.com.';
+  }
+  return 'an identical request is already awaiting approval.';
+};
+// Returns the disposition of a test/retest/instant-test request: an 'ok' disposition
+// describing how to check for completion, or a rejection disposition naming why the
+// request was not processed. Shared by requestNewTest, requestRetest, and orderNewTest,
+// whose only differences are the wording of the 3 completion-related sentences and, for
+// a rejection, the one extra requestResult branch getRequestFailureReason takes.
+export const buildRequestDisposition = (
+  requestResult: TestRequestResult,
+  okText: {whatHappensNext: string; howToCheck: string; howWebUserChecks: string},
+  extraBranch?: {result: TestRequestResult; reason: string}
+): RequestDisposition => {
+  if (requestResult === 'ok') {
+    return {
+      'what happens next': okText.whatHappensNext,
+      'how you can check for completion': okText.howToCheck,
+      'how a web user can check for completion': okText.howWebUserChecks
+    };
+  }
+  return {
+    'what happens next': `Your request will not be processed, because ${getRequestFailureReason(requestResult, extraBranch)}`,
+    'how you can check for completion': 'Not applicable.',
+    'how a web user can check for completion': 'Not applicable.'
+  };
+};
 // Returns the facts about a rule engine.
 export const getRuleEngineFacts = (ruleEngineID: string) => {
   const ruleEngineData = ruleEngines[ruleEngineID] || [null, null];

package/api/version.ts

@@ -1,8 +1,12 @@
 /*
   version.ts
-  Single source of truth for the version of the Kilotest API and MCP tool contract, consumed by mcp.ts and scripts/generate-openapi.ts.
+  Single source of truth for the version of the Kilotest API and MCP tool contract, consumed by mcp.ts and scripts/generate-openapi.ts. Re-exports package.json's version field verbatim, rather than hand-maintaining a separate literal here, so MCP and OpenAPI consumers see package.json's version exactly, including minor/patch bumps from changes that do not affect the API contract; this is a deliberate choice, not an oversight.
 */
 
+// IMPORTS
+
+import pkg from '../package.json' with {type: 'json'};
+
 // CONSTANTS
 
-export const version = '2.1.0';
+export const version = pkg.version;

package/capability.md

@@ -6,7 +6,7 @@ Web-page front-end quality audit. Kilotest tests web pages for front-end quality
 
 ## Purpose
 
-Language models and AI platforms often need accurate, page-specific data about the front-end quality of a web page to answer user questions. Rule engines, such as `axe-core`, `QualWeb`, and `WAVE`, provide such data, but with large coverage gaps. Orchestrating and reconciling numerous complementary rule engines would be difficult. Kilotest solves that problem by testing pages with an ensemble of numerous independent rule engines, making their results comparable, saving the results as JSON reports, mining the reports for facts at selectable levels of detail.
+Language models and AI platforms often need accurate, page-specific data about the front-end quality of a web page to answer user questions. Rule engines, such as `axe-core`, `QualWeb`, and `WAVE`, provide such data, but with large coverage gaps. Orchestrating and reconciling numerous complementary rule engines would be difficult. Kilotest solves that problem by testing pages with an ensemble of numerous independent rule engines, making their results comparable, saving the results as JSON reports, and mining the reports for facts at selectable levels of detail.
 
 ## Interfaces
 
@@ -26,17 +26,20 @@ A list of available reports.
 
 ## Subsequent inputs
 
-- If there is no report about the wanted page, a request to test it, with a page description and its URL.
-- If there is a report about the wanted page, requests for findings from the report at successive levels of detail.
+- If there is no report about the wanted page, a request or order for a new test, with a page description, its URL, and a reason for testing it.
+- If there is already a report about the wanted page, requests for findings from the report at successive levels of detail, or, if the report is deemed obsolete, a request or order for a retest, with a reason for retesting it.
+- Complaints and suggestions about features of Kilotest.
 
 ## Subsequent outputs
 
-- From a request to test a page: confirmation of receipt. Upon approval and execution, the list of available reports will include the new report.
+- From a **request** for a new test or a retest: if valid, confirmation of receipt. If the request is manager-approved and executed, the list of available reports will include the new report, typically in 1 hour to 1 day.
+- From an **order** for a new test or a retest: if valid, confirmation of receipt and immediate approval or rejection. If the request is approved, the output will include the identifier of the forthcoming report and two methods for getting the report: (1) allowing time (2 to 4 minutes) for completion of the report and then requesting it, and (2) making a request whose response will await the report and then link to it. Orders are enabled in the MCP and API interfaces only.
 - From a request for findings: Details about issues reported, related WCAG standards, what rules were violated, and which DOM elements violated them.
+- From complaints and suggestions about features: acknowledgment of receipt and of the manager being notified.
 
 ## Side effects
 
-Kilotest reads the specified web page during testing. It does not modify the target site. Testing is asynchronous and may take up to approximately one day before reports are available for newly requested pages.
+Kilotest reads the specified web page during testing. It does not modify the target site.
 
 ## Cost
 
@@ -49,3 +52,7 @@ MIT.
 ## Repository
 
 `https://github.com/jrpool/kilotest`
+
+## Privacy
+
+Kilotest requires no account. See the [privacy policy](https://kilotest.com/privacy.html).

package/docs/SERVICE.md

@@ -270,7 +270,7 @@ kilotest.com {
   }
   @allowedPOST {
     method POST
-    path /mcp /requestRetest.html/* /requestTest.html /requestAction.html /reannotate.html /renewWCAG.html /ai0BalanceForm.html /deleteNotesForm.html /expungeReportsForm.html /hideReportForm.html /metrics.html /pruneReportsForm.html /rewindReportsForm.html /showHiddenReportsForm.html /unhideReportForm.html /api/* /tutorialWebComment.html /tutorialAIComment.html /worker/job /worker/report
+    path /mcp /requestRetest.html/* /requestNewTest.html /requestAction.html /reannotate.html /renewWCAG.html /ai0BalanceForm.html /deleteNotesForm.html /expungeReportsForm.html /hideReportForm.html /metrics.html /pruneReportsForm.html /rewindReportsForm.html /showHiddenReportsForm.html /unhideReportForm.html /api/* /tutorialWebComment.html /tutorialAIComment.html /worker/job /worker/report
   }
   # Respond to OPTIONS requests.
   @allowedOPTIONS method OPTIONS
@@ -395,15 +395,13 @@ Alerts are sent to the maintainer in the following conditions:
 
 5. **Requested full report unavailable**: When a user requests a full report via the API but the report cannot be retrieved (e.g., the report file is missing from disk), an alert is sent with subject `"Kilotest: requested full report unavailable"`, including details on which report was requested and why it could not be retrieved.
 
-6. **Test request received via UI**: When a user submits a test request through the web interface, an alert is sent with subject `"Kilotest: new test request in the UI"` (via `/requestTest.html`) or `"Kilotest: new retest request in the UI"` (via `/requestRetest.html`), including the target URL, description, and the user's stated reason for the request. `test` and `retest` here are the only two literal values Kilotest passes as the request's type; they are hardcoded at each call site, not user-supplied.
+6. **Request for a test or retest received**: When a user submits a request to test or retest a page, whether through the web interface (`/requestNewTest.html` or `/requestRetest.html`) or the API (the `requestNewTest` or `requestRetest` operation), an alert is sent with subject `"Kilotest: request for a new test awaits approval"` or `"Kilotest: request for a retest awaits approval"`, including the target URL, description, and the user's stated reason for the request. Both the UI and API paths funnel through the same underlying request-queuing function, so the subject and the rest of this behavior are identical regardless of which path the request arrived through. A request is treated as a duplicate, and no alert is sent for it, only if a request already pending in `db/jobs/testRequests.json`, i.e., submitted but not yet manually approved by the maintainer into an actual job, for the same URL has the identical description; this check ignores the stated reason and the test-versus-retest distinction, and is not limited to a recent time window, it compares against every request still pending approval for that URL. Once the maintainer approves a pending request (turning it into a job via `/enqueue.html`), all pending requests for that URL are cleared, so this check cannot detect a duplicate against a request that has already been approved, is currently running, or has already completed; an identical request submitted after approval alerts again.
 
-7. **Test request received via API**: When a test request is submitted via the API, an alert is sent with subject `"Kilotest: new test request in the API"` (via the `requestTest` API operation) or `"Kilotest: new retest request in the API"` (via the `requestRetest` API operation), including the target URL, description, and the user's stated reason. A request is treated as a duplicate, and no alert is sent for it, only if a request already pending in `db/jobs/testRequests.json`, i.e., submitted but not yet manually approved by the maintainer into an actual job, for the same URL has the identical description; this check ignores the stated reason and the test-versus-retest distinction, and is not limited to a recent time window, it compares against every request still pending approval for that URL. Once the maintainer approves a pending request (turning it into a job via `/enqueue.html`), all pending requests for that URL are cleared, so this check cannot detect a duplicate against a request that has already been approved, is currently running, or has already completed; an identical request submitted after approval alerts again. The check and its dedup key are identical for the UI and API paths, since both funnel through the same underlying request-queuing function.
+7. **MCP feature request received**: When a user submits a feature request via the MCP server's `requestFeature` tool, an alert is sent with subject `"MCP feature request received"`, including the text of the feature request, and the request is also appended to `db/featureRequests.json`, the same way tutorial comments are appended to their own files (see item 1), so that a manager can review or delete it later via `/deleteNotesForm.html`.
 
-8. **MCP feature request received**: When a user submits a feature request via the MCP server's `requestFeature` tool, an alert is sent with subject `"MCP feature request received"`, including the text of the feature request, and the request is also appended to `db/featureRequests.json`, the same way tutorial comments are appended to their own files (see item 1), so that a manager can review or delete it later via `/deleteNotesForm.html`.
+8. **WAVE balance low**: When Kilotest detects that the account balance for the WAVE API service (used for accessibility testing) has fallen below a threshold, an alert is sent with subject `"Kilotest: WAVE balance low"`, indicating the number of credits remaining.
 
-9. **WAVE balance low**: When Kilotest detects that the account balance for the WAVE API service (used for accessibility testing) has fallen below a threshold, an alert is sent with subject `"Kilotest: WAVE balance low"`, indicating the number of credits remaining.
-
-10. **AI service balance low**: When Kilotest detects that the account balance for an AI service account (such as Anthropic) has fallen below a threshold, an alert is sent with subject `"Kilotest: AI service [N] balance low"`, indicating the approximate remaining balance in dollars and the estimated cost per job.
+9. **AI service balance low**: When Kilotest detects that the account balance for an AI service account (such as Anthropic) has fallen below a threshold, an alert is sent with subject `"Kilotest: AI service [N] balance low"`, indicating the approximate remaining balance in dollars and the estimated cost per job.
 
 ### Alert configuration
 
@@ -502,7 +500,7 @@ Kilotest records basic counts of how it is used, so the maintainer can answer qu
 
 - The generic `.html` GET dispatch in `index.ts`, once per successfully served web page, recorded under the `pageViews` category by page name (for example `tutorialWeb`, `listReports`), unless the page is a manager-only page (see "Manager page activity" below), in which case it is recorded there instead.
 - The home page (`/` and `/index.html`), served by its own branch in `index.ts` rather than through the generic `.html` dispatch, recorded under `pageViews` as `index`.
-- Each of the 9 MCP tool handlers in `mcp.ts`, once per successful tool call, recorded under the `mcpToolCalls` category by tool name (for example `listReports`, `requestTest`).
+- Each of the 9 MCP tool handlers in `mcp.ts`, once per successful tool call, recorded under the `mcpToolCalls` category by tool name (for example `listReports`, `requestNewTest`).
 - The `/api/*` GET and POST service branches in `index.ts`, once per call, recorded under the `apiOperations` category by operation name.
 
 `db/metrics.json` also stores a `since` time stamp, set when the file is first created, so the counts can be read as "since this date" rather than assumed to cover Kilotest's entire history. `getMetrics()` backfills any category absent from an existing `db/metrics.json` (for example one written before a category such as `managerActivity` existed), so an older file remains readable rather than causing every subsequent request to error.

package/env.example

@@ -47,6 +47,21 @@ TUTORIAL_WEB_COMMENTS_MAX=__placeholder__
 TUTORIAL_AI_COMMENTS_MAX=__placeholder__
 # Maximum number of feature requests held via the MCP server's requestFeature tool.
 FEATURE_REQUESTS_MAX=__placeholder__
+# Maximum number of jobs allowed in the job queue (db/jobs/queue) at once. Shared by every
+# path that enqueues a job: manager approval of a pending test/retest request, and the
+# orderNewTest/orderRetest MCP tools, which enqueue directly.
+JOB_QUEUE_MAX=__placeholder__
+
+# Timing for the awaitTest MCP tool's wait on a job ordered via orderNewTest/orderRetest.
+# Defaults: 2000ms poll interval, 300000ms (5 minutes) maximum wait. The maximum wait
+# deliberately exceeds the "occasionally up to 4 minutes" callers are told to expect, to
+# leave margin so a job that is genuinely still running is not mistaken for one that
+# never will finish. Lower values are useful for local testing.
+
+# Milliseconds between polls while awaitTest waits for a job to complete.
+AWAIT_JOB_POLL_MS=__placeholder__
+# Maximum milliseconds awaitTest waits before giving up.
+AWAIT_JOB_TIMEOUT_MS=__placeholder__
 
 # Alert configuration:
 

package/index.html

@@ -90,6 +90,7 @@
         <li><a href="listReports.html">Which web pages have been tested?</a></li>
         <li><a href="listTopIssues.html">Which issues have been reported?</a></li>
         <li><a href="manage.html">What can Kilotest managers do?</a></li>
+        <li><a href="privacy.html">What is the privacy policy?</a></li>
       </ul>
     </main>
   </body>