@jrpool/kilotest 52.0.0 → 57.0.1

package/api/{requestTest.ts → requestNewTest.ts}

@@ -1,19 +1,20 @@
 /*
-  requestTest.ts
+  requestNewTest.ts
   Processes a request to test an untested page and returns an acknowledgement.
 */
 
 // IMPORTS
 
 import {z} from 'zod';
-import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
-import {checkLength, isAllowedTarget, isURL, processTestRequest} from '../util.ts';
-import {requestTestResponseSchema} from './schemas.ts';
+import {buildRequestDisposition, getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
+import {checkLength, isAllowedRedirectTarget, isAllowedTarget, isURL, processTestRequest} from '../util.ts';
+import {requestNewTestResponseSchema} from './schemas.ts';
+import {sendAlert} from '../alerts.ts';
 
 // TYPES
 
 // The response content defined by the response schema.
-type ResponseContent = z.infer<typeof requestTestResponseSchema>['response content'];
+type ResponseContent = z.infer<typeof requestNewTestResponseSchema>['response content'];
 
 // FUNCTIONS
 
@@ -49,6 +50,19 @@ export const response = async (args: string[]) => {
       error: 'request invalid: the URL you specified does not resolve to a page that this deployment can test'
     };
   }
+  // Otherwise, i.e. if the URL redirects to a target this deployment does not allow:
+  else if (!(await isAllowedRedirectTarget(url))) {
+    requestDetails = {
+      error: 'request invalid: the URL you specified does not resolve to a page that this deployment can test'
+    };
+    // Alert a manager, since a redirect to a disallowed target on a request that
+    // itself named an allowed hostname suggests an attempted or accidental SSRF,
+    // rather than an ordinary mistake by a legitimate submitter.
+    await sendAlert(
+      'Kilotest: request rejected for redirecting to a disallowed target',
+      `A request to test ${url} (described as "${description}") was rejected because it redirects to a target this deployment does not allow (e.g. a private, loopback, or link-local address).`
+    );
+  }
   // Otherwise, i.e. if the description and URL are valid:
   else {
     // Process the request.
@@ -63,34 +77,15 @@ export const response = async (args: string[]) => {
       'reason why the page should be tested': 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 tested and a 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 tested and a 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 === 'retest') {
-        failureReason = 'a report about a page with the same description and URL is available.'
-      }
-      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 tested and a report is available.',
+        howWebUserChecks: `A web user can visit ${thisHost}/listReports.html to learn whether the page has been tested and a report is available.`
+      },
+      {result: 'reportExists', reason: 'a report about a page with the same description and URL is available.'}
+    );
   }
   // Create the response content.
   const responseContent: ResponseContent = {
@@ -100,11 +95,11 @@ export const response = async (args: string[]) => {
   // Create a response body.
   const body = {
     'tool collection': getToolsFacts(),
-    'tool name': 'requestTest',
+    'tool name': 'requestNewTest',
     'this request': {
       description: 'Process my request to test a page about which no report is available yet. I have provided a description and the URL of the page and a reason why it should be tested.',
       method: 'POST',
-      URL: `${thisHost}/api/requestTest`,
+      URL: `${thisHost}/api/requestNewTest`,
       body: {
         description,
         URL: url,
@@ -118,7 +113,7 @@ export const response = async (args: string[]) => {
       }
     },
     'URLs of similar requests for web users': {
-      'this request': `${thisHost}/requestTestForm.html`,
+      'this request': `${thisHost}/requestNewTestForm.html`,
       'closest ancestor request': `${thisHost}/listReports.html`
     },
     'response metadata': getResponseMetadata(),

package/api/requestRetest.test.ts

@@ -74,14 +74,14 @@ test('requestRetest rejects a nonexistent report', async () => {
   const body = await response(['251231T0000', 'zzz', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('does not exist'));
-  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+  assert.ok(!logged.some(line => line.includes('request for a retest awaits approval')));
 });
 
 test('requestRetest rejects a malformed timestamp or job identifier', async () => {
   const body = await response(['999999T9999', 'xyz', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('malformed'));
-  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+  assert.ok(!logged.some(line => line.includes('request for a retest awaits approval')));
 });
 
 test('requestRetest rejects a superseded report', async () => {
@@ -95,14 +95,14 @@ test('requestRetest rejects a superseded report', async () => {
   assert.ok(
     disposition['what happens next'].includes('a later report about a page with the same description is available.')
   );
-  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+  assert.ok(!logged.some(line => line.includes('request for a retest awaits approval')));
 });
 
 test('requestRetest rejects a reason shorter than 20 characters', async () => {
   const body = await response(['260101T0003', 'ret', 'short']);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
-  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+  assert.ok(!logged.some(line => line.includes('request for a retest awaits approval')));
 });
 
 test('requestRetest rejects a reason longer than 100 characters', async () => {
@@ -110,7 +110,7 @@ test('requestRetest rejects a reason longer than 100 characters', async () => {
   const body = await response(['260101T0003', 'ret', longReason]);
   const details = body['response content']['details about your request'] as any;
   assert.ok(details.error.includes('reason'));
-  assert.ok(!logged.some(line => line.includes('new retest request awaits approval')));
+  assert.ok(!logged.some(line => line.includes('request for a retest awaits approval')));
 });
 
 test('requestRetest rejects a report matching a claimed job by description', async () => {
@@ -170,8 +170,26 @@ test('requestRetest accepts a valid retest request for the latest report of a pa
   assert.equal(details.error, undefined);
   assert.equal(details['page to be retested'].description, 'Mixed Outcomes Page');
   assert.ok(logged.some(line =>
-    line.startsWith('WARNING (Kilotest: new retest request awaits approval)')
+    line.startsWith('WARNING (Kilotest: request for a retest awaits approval)')
     && line.includes('Mixed Outcomes Page')
     && line.includes('https://example.com/mixed')
+    // The alert reports the resulting queue size, so a maintainer who has been away can
+    // see at a glance how close the queue is to full.
+    && line.includes('Requests now awaiting approval: 1 of 20')
   ));
 });
+
+test('requestRetest rejects a request with a fallback channel when the queue is full', async () => {
+  // Fill testRequests.json with 20 pending requests, all for one URL, to reach the cap.
+  const filler = Array.from({length: 20}, (_, i) => ({
+    timeStamp: '260101T0000', description: `Filler Page ${i}`, reason: 'Filler reason.'
+  }));
+  await fs.writeFile(testRequestsPath, JSON.stringify({'https://example.com/filler': filler}));
+  const body = await response(['260101T0003', 'ret', 'A reason that is long enough.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.equal(details.error, undefined);
+  const disposition = body['response content']['disposition of your request'] as any;
+  assert.ok(disposition['what happens next'].includes('too many requests are awaiting approval right now.'));
+  assert.ok(disposition['what happens next'].includes('https://github.com/jrpool/kilotest/issues'));
+  assert.ok(disposition['what happens next'].includes('info@kilotest.com'));
+});

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,34 +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 {
-          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;