@jrpool/kilotest 52.0.0 → 55.0.0

package/.devin/config.local.json

@@ -36,7 +36,10 @@
       "Exec(git mv)",
       "Exec(perl)",
       "Exec(ssh)",
-      "Exec(scp)"
+      "Exec(scp)",
+      "Exec(sqlite3)",
+      "Exec(npm update)",
+      "Exec(npm ls)"
     ]
   }
 }

package/.github/workflows/ci.yml

@@ -22,6 +22,9 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: Run typecheck
+        run: npm run typecheck
+
       - name: Run lint
         run: npm run lint
 

package/api/requestFeature.test.ts

@@ -81,9 +81,45 @@ test('requestFeature accepts a non-empty feature request and notifies the manage
   assert.ok(logged.some(line =>
     line.startsWith('WARNING (Kilotest: MCP feature request received)')
     && line.includes('Add a dark mode toggle')
+    // 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('Feature requests now awaiting review: 1 of 20')
   ));
 });
 
+test('requestFeature rejects a request with a fallback channel when the queue is full', async () => {
+  // Fill featureRequests.json with 20 distinct requests, reaching the cap.
+  const filler = Array.from({length: 20}, (_, i) => ({
+    timeStamp: '260101T0000', content: `Filler feature request number ${i}, long enough to pass the length check.`
+  }));
+  await fs.writeFile(process.env.FEATURE_REQUESTS_PATH!, JSON.stringify(filler));
+  const body = await response(['One feature request too many, long enough to pass the length check.']);
+  const details = body['response content']['details about your request'] as any;
+  assert.ok(details.error.includes('too many feature requests are awaiting review right now.'));
+  assert.ok(details.error.includes('https://github.com/jrpool/kilotest/issues'));
+  assert.ok(details.error.includes('info@kilotest.com'));
+  const featureRequests = JSON.parse(await fs.readFile(process.env.FEATURE_REQUESTS_PATH!, 'utf8'));
+  // The rejected request was not recorded.
+  assert.equal(featureRequests.length, 20);
+});
+
+test('requestFeature never rejects for a full inbox when FEATURE_REQUESTS_MAX is 0 (no limit)', async () => {
+  process.env.FEATURE_REQUESTS_MAX = '0';
+  try {
+    // Fill featureRequests.json past the default cap.
+    const filler = Array.from({length: 25}, (_, i) => ({
+      timeStamp: '260101T0000', content: `Filler feature request number ${i}, long enough to pass the length check.`
+    }));
+    await fs.writeFile(process.env.FEATURE_REQUESTS_PATH!, JSON.stringify(filler));
+    const body = await response(['One more feature request, long enough to pass the length check.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.equal(details.error, undefined);
+  }
+  finally {
+    delete process.env.FEATURE_REQUESTS_MAX;
+  }
+});
+
 test('requestFeature includes tool name and metadata', async () => {
   const body = await response(['A sufficiently long feature description']);
   assert.equal(body['tool name'], 'requestFeature');

package/api/requestFeature.ts

@@ -8,7 +8,7 @@
 import {z} from 'zod';
 import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
 import {sendAlert} from '../alerts.ts';
-import {checkCommentDuplicate, checkLength, getJSON, getNowStamp} from '../util.ts';
+import {checkCommentDuplicate, checkLength, describeMax, getEnvMax, getJSON, getNowStamp} from '../util.ts';
 import {requestFeatureResponseSchema} from './schemas.ts';
 import fs from 'node:fs/promises';
 import path from 'node:path';
@@ -21,6 +21,13 @@ type ResponseContent = z.infer<typeof requestFeatureResponseSchema>['response co
 // FUNCTIONS (helpers)
 
 const getFeatureRequestsPath = () => process.env.FEATURE_REQUESTS_PATH || path.join(import.meta.dirname, '../db/featureRequests.json');
+// Maximum number of feature requests held at once. Once reached, a new, distinct request
+// is rejected rather than stored, so the feature-requests file and the manager alert
+// emails it generates cannot grow without bound (modeled on a full mailbox rejecting new
+// mail; see GitHub issue #3, abuse type 3). Configurable via FEATURE_REQUESTS_MAX, since
+// different Kilotest deployments' maintainers may want a different size; a value of 0
+// means no limit.
+const getFeatureRequestsMax = () => getEnvMax('FEATURE_REQUESTS_MAX', 20);
 
 // FUNCTIONS
 
@@ -61,7 +68,18 @@ export const response = async (args: string[]) => {
         }
       };
     }
-    // Otherwise, i.e. if it is not a duplicate:
+    // Otherwise, if the feature requests already on file have reached the cap (a cap of 0
+    // means no limit, so the queue is never full):
+    else if (getFeatureRequestsMax() > 0 && featureRequests.length >= getFeatureRequestsMax()) {
+      responseContent = {
+        'details about your request': {
+          error: 'request invalid: too many feature requests are awaiting review right now. ' +
+            'Please try again later, or post your request at https://github.com/jrpool/kilotest/issues ' +
+            'or email info@kilotest.com.'
+        }
+      };
+    }
+    // Otherwise, i.e. if it is not a duplicate and the queue is not full:
     else {
       // Record the feature request alongside the existing ones.
       featureRequests.push({
@@ -70,8 +88,12 @@ export const response = async (args: string[]) => {
       });
       await fs.mkdir(path.dirname(featureRequestsPath), {recursive: true});
       await fs.writeFile(featureRequestsPath, getJSON(featureRequests));
-      // Notify the manager.
-      await sendAlert('Kilotest: MCP feature request received', feature);
+      // Notify the manager, including the resulting count, so a maintainer who has been
+      // away sees at a glance how urgently the requests need review.
+      await sendAlert(
+        'Kilotest: MCP feature request received',
+        `${feature}\nFeature requests now awaiting review: ${featureRequests.length} of ${describeMax(getFeatureRequestsMax())}`
+      );
       // Add the disposition to the response content.
       responseContent = {
         'details about your request': {

package/api/requestRetest.test.ts

@@ -173,5 +173,23 @@ test('requestRetest accepts a valid retest request for the latest report of a pa
     line.startsWith('WARNING (Kilotest: new retest request 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

@@ -79,6 +79,10 @@ export const response = async (args: string[]) => {
         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.'
         }

package/api/requestTest.test.ts

@@ -93,6 +93,22 @@ test('requestTest rejects a private-address URL unless internal targets are allo
   }
 });
 
+test('requestTest rejects a URL that redirects to a disallowed target, and alerts a manager', async (t) => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  t.mock.method(globalThis, 'fetch', async () => ({url: 'https://10.0.0.5/page'}) as Response);
+  try {
+    const body = await response(['Redirecting Page', 'https://example.com/redirector', 'A reason that is long enough.']);
+    const details = body['response content']['details about your request'] as any;
+    assert.ok(details.error.includes('does not resolve to a page that this deployment can test'));
+    assert.ok(logged.some(line =>
+      line.includes('WARNING (Kilotest: request rejected for redirecting to a disallowed target)')
+      && line.includes('https://example.com/redirector')
+    ));
+  } finally {
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+  }
+});
+
 test('requestTest rejects an already-tested page', async () => {
   const body = await response(['Mixed Outcomes Page', 'https://example.com/mixed', 'A reason that is long enough.']);
   const details = body['response content']['details about your request'] as any;
@@ -165,6 +181,9 @@ test('requestTest accepts a valid new page request', async () => {
     line.startsWith('WARNING (Kilotest: new test request awaits approval)')
     && line.includes('Brand New Page')
     && line.includes('https://example.com/brandnew')
+    // 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')
   ));
 });
 
@@ -174,3 +193,18 @@ test('requestTest includes disposition information for a valid request', async (
   assert.ok(disposition);
   assert.ok(disposition['what happens next']);
 });
+
+test('requestTest 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(['One Too Many Page', 'https://example.com/one-too-many', '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/requestTest.ts

@@ -7,8 +7,9 @@
 
 import {z} from 'zod';
 import {getResponseMetadata, getThisHost, getToolsFacts} from './util.ts';
-import {checkLength, isAllowedTarget, isURL, processTestRequest} from '../util.ts';
+import {checkLength, isAllowedRedirectTarget, isAllowedTarget, isURL, processTestRequest} from '../util.ts';
 import {requestTestResponseSchema} from './schemas.ts';
+import {sendAlert} from '../alerts.ts';
 
 // TYPES
 
@@ -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.
@@ -82,6 +96,10 @@ export const response = async (args: string[]) => {
       else if (requestResult === 'retest') {
         failureReason = 'a report about a page with the same description and URL 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.'
       }

package/capability.md

@@ -2,7 +2,7 @@
 
 ## Capability
 
-Web-page front-end quality audit. Kilotest tests public web pages for front-end quality, namely accessibility, usability, and standards conformity, and makes structured findings available for retrieval.
+Web-page front-end quality audit. Kilotest tests web pages for front-end quality, namely accessibility, usability, and standards conformity, and makes structured findings available for retrieval.
 
 ## Purpose
 
@@ -36,7 +36,7 @@ A list of available reports.
 
 ## Side effects
 
-Kilotest reads the specified public 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. Testing is asynchronous and may take up to approximately one day before reports are available for newly requested pages.
 
 ## Cost
 

package/docs/AI-TOOLS.md

@@ -42,7 +42,7 @@ The external features that support the use of Kilotest as a collection of AI too
 - A [pull request](https://github.com/public-apis/public-apis/pull/6346/changes) to add Kilotest to the list of public APIs in the `public-apis` repository.
 - An [issue](https://github.com/APIs-guru/openapi-directory/issues/2677) to add Kilotest to `openapi-directory`.
 - A [pull request](https://github.com/w3c/wai-evaluation-tools-list/pull/1153) to add Kilotest to the WAI evaluation tools list.
-- Registration of Kilotest as an active server in the [official MCP Registry](https://registry.modelcontextprotocol.io/v0/servers?search=kilotest) (`io.github.jrpool/kilotest`), maintained by the [Model Context Protocol](https://modelcontextprotocol.io/) project. The [PulseMCP](https://www.pulsemcp.com/servers) directory and the VS Code MCP gallery both crawl this registry, so Kilotest is discoverable through them with no separate submission.
+- Registration of Kilotest as an active server in the [official MCP Registry](https://registry.modelcontextprotocol.io) (`io.github.jrpool/kilotest`), maintained by the [Model Context Protocol](https://modelcontextprotocol.io/) project. The [PulseMCP](https://www.pulsemcp.com/servers) directory and the VS Code MCP gallery both crawl this registry, so Kilotest is discoverable through them with no separate submission.
 - Registration of Kilotest with the [Smithery](https://smithery.ai/servers/pool/kilotest) MCP server registry.
 - Registration of Kilotest with the [Glama](https://glama.ai/mcp/connectors/com.kilotest/kilotest) MCP server registry, including a claim of ownership of the MCP connector by the maintainer via a `TXT` DNS record for `_glama-claim.kilotest.com`, with the value `glama_claim_gVV4HrPdcXr9TEfj1p3icEUBJ3_OVJGX`.
 - Registration of Kilotest with [Awesome MCP Servers](https://www.tensorblock.co/mcp/servers/github-jrpool-kilotest-f518ba36).
@@ -107,7 +107,7 @@ Other future work:
     Capability: web-page-quality-audit
 
     Purpose:
-      Test a public web page for accessibility,
+      Test a web page for accessibility,
       usability, HTML and web-standards problems.
 
     Interfaces:
@@ -123,7 +123,7 @@ Other future work:
       rule-engine diagnoses, WCAG mappings
 
     Side effects:
-      Reads the specified public web page.
+      Reads the specified web page.
       Does not modify the target site.
 
     Cost:

package/docs/SERVICE.md

@@ -417,6 +417,19 @@ Alerts are sent via the `sendAlert()` function in [alerts.ts](../alerts.ts), whi
 
 If any of these five variables is missing or empty at alert time, the alert is not sent. Instead, a warning message is logged to the console, and the application continues normal operation. The warning includes the alert subject and body so the maintainer can manually review what would have been sent.
 
+### Inbox size limits
+
+Four submission types (test requests and retest requests together, web tutorial comments, AI tutorial comments, and MCP feature requests) are each held in a pending "inbox" (`db/jobs/testRequests.json`, `db/comments/tutorialWeb.json`, `db/comments/tutorialAI.json`, and `db/featureRequests.json` respectively) awaiting manual review by the maintainer. Each inbox has a maximum size; once reached, a new, distinct submission is rejected (with a message suggesting the requester instead post to the [GitHub issues page](https://github.com/jrpool/kilotest/issues) or email `info@kilotest.com`) rather than added, so neither the inbox file nor the manager alert emails it generates can grow without bound (see GitHub issue #3, abuse type 3, repeated/automated submissions). This is modeled on a full mailbox rejecting new mail, rather than on a submission rate limit: it is the backlog size itself, not how quickly it grows, that costs the maintainer review time and risks unbounded storage. Every alert sent for an accepted submission reports the resulting inbox count against its cap, so a maintainer returning after an absence can immediately see how close an inbox is to full.
+
+Each cap defaults to 20 and can be set independently via an environment variable:
+
+1. **`TEST_REQUEST_QUEUE_MAX`**: The maximum number of test and retest requests awaiting approval at once, summed across all requested URLs.
+2. **`TUTORIAL_WEB_COMMENTS_MAX`**: The maximum number of comments held on the web tutorial page (`/tutorialWeb.html`).
+3. **`TUTORIAL_AI_COMMENTS_MAX`**: The maximum number of comments held on the AI agent tutorial page (`/tutorialAI.html`).
+4. **`FEATURE_REQUESTS_MAX`**: The maximum number of feature requests held via the MCP server's `requestFeature` tool.
+
+Each variable, if set, must be a non-negative integer; if unset, empty, or not a non-negative integer, the default of 20 is used instead. A value of `0` means no limit: that inbox is never treated as full, regardless of size. Unlike the alert-configuration variables above, these are not required: an unset value never disables the limit, it only selects the default size.
+
 ### Resend integration
 
 Kilotest uses [Resend](https://resend.com/) as its transactional email delivery service. Resend is configured through the environment variables above.
@@ -489,7 +502,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 8 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`, `requestTest`).
 - 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

@@ -2,6 +2,12 @@
 ENVIRONMENT=__placeholder__
 # http (local or reverse-proxied server) or https.
 PROTOCOL=__placeholder__
+# Port the server listens on (defaults to 3000).
+PORT=__placeholder__
+# Path of the private key file. Required only when PROTOCOL is https.
+KEY=__placeholder__
+# Path of the certificate file. Required only when PROTOCOL is https.
+CERT=__placeholder__
 # 3-character password for manager operations.
 AUTH_CODE=__placeholder__
 # ID of each Testaro worker and, for each, its secret and published name.
@@ -23,6 +29,24 @@ DB_DIR=__placeholder__
 # since such a worker could otherwise be induced to fetch a target it has no legitimate reason
 # to reach, such as its own host’s cloud-metadata service.
 ALLOW_INTERNAL_TARGETS=__placeholder__
+# Path of the web tutorial comments file (defaults to db/comments/tutorialWeb.json).
+TUTORIAL_WEB_COMMENTS_PATH=__placeholder__
+# Path of the AI tutorial comments file (defaults to db/comments/tutorialAI.json).
+TUTORIAL_AI_COMMENTS_PATH=__placeholder__
+# Path of the feature requests file (defaults to db/featureRequests.json).
+FEATURE_REQUESTS_PATH=__placeholder__
+
+# Inbox size limits: each defaults to 20 if unset, empty, or not a non-negative integer.
+# A value of 0 means no limit.
+
+# Maximum number of test/retest requests awaiting approval at once, across all URLs.
+TEST_REQUEST_QUEUE_MAX=__placeholder__
+# Maximum number of comments held on the web tutorial page.
+TUTORIAL_WEB_COMMENTS_MAX=__placeholder__
+# Maximum number of comments held on the AI agent tutorial page.
+TUTORIAL_AI_COMMENTS_MAX=__placeholder__
+# Maximum number of feature requests held via the MCP server's requestFeature tool.
+FEATURE_REQUESTS_MAX=__placeholder__
 
 # Alert configuration:
 

package/index.test.ts

@@ -1166,6 +1166,57 @@ test('POST /worker/job with a queued job assigns it to the worker', {timeout: 50
   await fs.unlink(path.join(claimedDir, jobFile)).catch(() => {});
 });
 
+test('POST /worker/job with a queued job whose host now redirects to a disallowed target rejects it without assigning it', {timeout: 500}, async (t) => {
+  delete process.env.ALLOW_INTERNAL_TARGETS;
+  // Clean up claimed, queue, and failed directories.
+  const claimedDir = path.join(fixtureDBDir, 'jobs', 'claimed');
+  const queueDir = path.join(fixtureDBDir, 'jobs', 'queue');
+  const failedDir = path.join(fixtureDBDir, 'jobs', 'failed');
+  for (const dir of [claimedDir, queueDir]) {
+    await fs.mkdir(dir, {recursive: true});
+    const files = await fs.readdir(dir).catch(() => []);
+    for (const file of files) {
+      await fs.unlink(path.join(dir, file)).catch(() => {});
+    }
+  }
+  const jobFile = '260101T0000-mix.json';
+  const failedJobPath = path.join(failedDir, jobFile);
+  await fs.unlink(failedJobPath).catch(() => {});
+  // The job's host still resolves publicly, but by the time it is dequeued for
+  // assignment it has been reconfigured (e.g. by an attacker) to redirect to a
+  // private address, which only a fetch-based check, not a DNS-only one, can see.
+  t.mock.method(globalThis, 'fetch', async () => ({url: 'https://192.168.1.1/test'}) as Response);
+  try {
+    await fs.writeFile(path.join(queueDir, jobFile), JSON.stringify({
+      id: '260101T0000-mix',
+      target: {what: 'Test Page', url: 'https://example.com/test'},
+      sources: {}
+    }));
+    const auth = Buffer.from('worker1:secret1').toString('base64');
+    const res = await request('POST', '/worker/job', {}, {
+      authorization: `Basic ${auth}`
+    });
+    // The worker should be told there is no job, not given the disallowed job.
+    assert.equal(res.statusCode, 200);
+    const body = jsonBody(res);
+    assert.equal(body.id, undefined);
+    // Wait for the async rename to complete.
+    await new Promise<void>(resolve => setTimeout(resolve, 100));
+    // The job should have been moved from queue to failed, never to claimed.
+    const queueExists = await fs.access(path.join(queueDir, jobFile)).then(() => true).catch(() => false);
+    assert.equal(queueExists, false, 'Job should be removed from queue');
+    const claimedExists = await fs.access(path.join(claimedDir, jobFile)).then(() => true).catch(() => false);
+    assert.equal(claimedExists, false, 'Job should not be moved to claimed directory');
+    const failedExists = await fs.access(failedJobPath).then(() => true).catch(() => false);
+    assert.ok(failedExists, 'Job should be moved to the failed directory');
+  } finally {
+    t.mock.reset();
+    process.env.ALLOW_INTERNAL_TARGETS = 'true';
+    // Clean up.
+    await fs.unlink(failedJobPath).catch(() => {});
+  }
+});
+
 // TESTS: worker/report valid submission
 
 test('POST /worker/report with valid authentication and valid claimed job processes the report', {timeout: 500}, async () => {

package/index.ts

@@ -17,6 +17,7 @@ import {
   getObject,
   getPOSTData,
   getReport,
+  isAllowedRedirectTarget,
   isAllowedReport,
   isAllowedTarget,
   isReportError,
@@ -484,26 +485,54 @@ const processJobRequest = async (request: IncomingMessage, response: ServerRespo
     if (queuedJobNames.length) {
       const oldestJobName = queuedJobNames[0]!;
       // Get the first one.
-      const firstJob = await getObject(path.join(queuePath(), oldestJobName)) as {id: string, sources: {worker: string}, target: {what: string}};
-      // Add the public worker name to the job, in a property Testaro does not read or alter.
-      firstJob.sources.worker = workerName;
-      console.log(
-        `Job ${firstJob.id} (${firstJob.target.what}) is being sent to the worker.`
-      );
-      // Assign the job to the worker.
-      response.writeHead(200, {
-        'content-type': 'application/json; charset=utf-8'
-      });
-      response.end(JSON.stringify(firstJob));
-      const messageEnd
-      = `and job ${firstJob.id} (${firstJob.target.what}) was assigned to the worker`;
-      console.log(`${messageStart}${messageEnd}`);
-      // Save the job in the claimed-jobs directory.
-      await fs.writeFile(
-        path.join(claimedPath(), oldestJobName), getJSON(firstJob)
-      );
-      // Delete it from the queue.
-      await fs.unlink(path.join(queuePath(), oldestJobName));
+      const firstJob = await getObject(path.join(queuePath(), oldestJobName)) as {id: string, sources: {worker: string}, target: {what: string, url: string}};
+      // If the job's target is no longer allowed, whether because its host now resolves
+      // to a disallowed address or, more likely, because the host now redirects to one
+      // (both possible if the target host was reconfigured, e.g. by an attacker, after
+      // the request was accepted; a fetch-based check is used, rather than the cheaper
+      // DNS-only isAllowedTarget, because this runs only when a job is actually queued,
+      // which is rare, and a redirect introduced after acceptance is the likelier attack):
+      if (!(await isAllowedRedirectTarget(firstJob.target.url))) {
+        console.error(`ERROR: Queued job ${firstJob.id} is on a target this deployment does not allow`);
+        // Alert a manager, since this indicates an attempted or accidental SSRF
+        // rather than an ordinary usability problem with the target.
+        await sendAlert(
+          'Kilotest: queued job on disallowed target rejected',
+          `Job ${firstJob.id} (${firstJob.target.what}) was never assigned to a worker because its target no longer resolves, directly or via a redirect, to an address this deployment allows (e.g. a private, loopback, or link-local address). The job was reclassified as failed.`
+        );
+        // Reclassify the job as failed, instead of assigning it or leaving it queued.
+        await fs.rename(
+          path.join(queuePath(), oldestJobName), path.join(failedPath(), oldestJobName)
+        );
+        // Respond as if no job were queued, rather than revealing anything about the rejected job.
+        response.writeHead(200, {
+          'content-type': 'application/json; charset=utf-8'
+        });
+        response.end(JSON.stringify({}));
+        console.log(`${messageStart}but the queued job was on a disallowed target`);
+      }
+      // Otherwise, i.e. if the job's target is still allowed:
+      else {
+        // Add the public worker name to the job, in a property Testaro does not read or alter.
+        firstJob.sources.worker = workerName;
+        console.log(
+          `Job ${firstJob.id} (${firstJob.target.what}) is being sent to the worker.`
+        );
+        // Assign the job to the worker.
+        response.writeHead(200, {
+          'content-type': 'application/json; charset=utf-8'
+        });
+        response.end(JSON.stringify(firstJob));
+        const messageEnd
+        = `and job ${firstJob.id} (${firstJob.target.what}) was assigned to the worker`;
+        console.log(`${messageStart}${messageEnd}`);
+        // Save the job in the claimed-jobs directory.
+        await fs.writeFile(
+          path.join(claimedPath(), oldestJobName), getJSON(firstJob)
+        );
+        // Delete it from the queue.
+        await fs.unlink(path.join(queuePath(), oldestJobName));
+      }
     }
     // Otherwise, i.e. if no jobs are queued:
     else {

package/llms-full.txt

@@ -6,7 +6,7 @@ Kilotest is an application that performs ensemble testing of web pages for front
 
 ## What Kilotest does for language models
 
-Kilotest is deployed on the public Internet as a service at `https://kilotest.com`. Kilotest can test only web pages that can be accessed from the public Internet and that are not protected by authentication or other access controls. Kilotest has not implemented any mechanism for testing private, internal, password-protected, or otherwise restricted pages.
+Kilotest is deployed on the public Internet as a service at `https://kilotest.com`. That deployment of Kilotest can test only web pages that can be accessed by its Testaro worker with a URL. Generally those are pages on the public Internet that are not protected by authentication or other access controls.
 
 Without calling any tool, an LLM can, under some conditions, load web pages and use its knowledge to assess successes and failures of front-end quality. But such an assessment is almost always:
 

package/llms.txt

@@ -1,6 +1,6 @@
 # Kilotest
 
-Kilotest helps language models and AI platforms to give thorough, accurate and truthful answers when users ask about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages. Kilotest integrates an ensemble of twelve independent rule engines to test any public web page. Kilotest creates a structured report of the results and saves the report for future reference. Kilotest API endpoints and MCP tools can provide multipage, single-page, and element-level test results.
+Kilotest helps language models and AI platforms to give thorough, accurate and truthful answers when users ask about the front-end quality (i.e. accessibility, usability, and standards conformity) of web pages. Kilotest integrates an ensemble of twelve independent rule engines to test a web page. Kilotest creates a structured report of the results and saves the report for future reference. Kilotest API endpoints and MCP tools can provide multipage, single-page, and element-level test results.
 
 ## API
 

package/mcp.test.ts

@@ -11,6 +11,8 @@ import http from 'node:http';
 import {mcpPath, createMCPServer, handleMCP} from './mcp.ts';
 import {metricsPath} from './util.ts';
 import fs from 'node:fs';
+import {Client} from '@modelcontextprotocol/sdk/client/index.js';
+import {InMemoryTransport} from '@modelcontextprotocol/sdk/inMemory.js';
 
 // CONSTANTS
 
@@ -35,11 +37,12 @@ test('mcpPath is /mcp', () => {
   assert.equal(mcpPath, '/mcp');
 });
 
-test('createMCPServer registers all 8 tools', () => {
+test('createMCPServer registers all 9 tools', () => {
   const server = createMCPServer();
   const toolNames = Object.keys((server as any)._registeredTools);
-  assert.equal(toolNames.length, 8);
+  assert.equal(toolNames.length, 9);
   assert.deepEqual(toolNames, [
+    'getKilotestOverview',
     'listReports',
     'listIssues',
     'listViolators',
@@ -56,10 +59,41 @@ test('each tool has a description and a handler function', () => {
   const tools = (server as any)._registeredTools;
   for (const [name, tool] of Object.entries(tools) as [string, any][]) {
     assert.ok(tool.description, `${name} has a description`);
+    assert.ok(
+      tool.description.includes('front-end quality'),
+      `${name} description includes the shared domain context`
+    );
     assert.equal(typeof tool.handler, 'function', `${name} has a handler function`);
   }
 });
 
+test('getKilotestOverview handler returns overview text and records a metric', async () => {
+  const server = createMCPServer();
+  const countBefore = getToolCallCount('getKilotestOverview');
+  const result = await (server as any)._registeredTools.getKilotestOverview.handler({});
+  assert.ok(result.content);
+  assert.equal(result.content[0].type, 'text');
+  assert.ok(result.content[0].text.includes('front-end quality'));
+  assert.equal(getToolCallCount('getKilotestOverview'), countBefore + 1);
+});
+
+test('client receives instructions, server description, and the overview resource', async () => {
+  const server = createMCPServer();
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
+  await server.connect(serverTransport);
+  const client = new Client({name: 'test-client', version: '1.0.0'});
+  await client.connect(clientTransport);
+  assert.ok(client.getInstructions()?.includes('front-end quality'));
+  assert.ok(client.getServerVersion()?.description?.includes('front-end quality'));
+  const resources = await client.listResources();
+  assert.deepEqual(resources.resources.map((r: any) => r.uri), ['docs://kilotest/overview']);
+  const read = await client.readResource({uri: 'docs://kilotest/overview'});
+  assert.equal(read.contents[0]?.mimeType, 'text/plain');
+  assert.ok((read.contents[0] as any).text.includes('front-end quality'));
+  await client.close();
+  await server.close();
+});
+
 test('listReports handler returns content and structuredContent', async () => {
   const server = createMCPServer();
   const countBefore = getToolCallCount('listReports');
@@ -258,6 +292,8 @@ test('handleMCP responds to initialize with server info', async () => {
     assert.equal(res.statusCode, 200);
     const result = parseSSEResult(res.body);
     assert.equal(result.result.serverInfo.name, 'Kilotest');
+    assert.ok(result.result.serverInfo.description.includes('front-end quality'));
+    assert.ok(result.result.instructions.includes('front-end quality'));
     assert.equal(result.result.protocolVersion, '2025-06-18');
   }
   finally {
@@ -265,7 +301,7 @@ test('handleMCP responds to initialize with server info', async () => {
   }
 });
 
-test('handleMCP lists all 8 tools via tools/list', async () => {
+test('handleMCP lists all 9 tools via tools/list', async () => {
   const server = await startMCPServer();
   try {
     const port = server.address().port;
@@ -273,8 +309,9 @@ test('handleMCP lists all 8 tools via tools/list', async () => {
     assert.equal(res.statusCode, 200);
     const result = parseSSEResult(res.body);
     const toolNames = result.result.tools.map((t: any) => t.name);
-    assert.equal(toolNames.length, 8);
+    assert.equal(toolNames.length, 9);
     assert.deepEqual(toolNames, [
+      'getKilotestOverview',
       'listReports',
       'listIssues',
       'listViolators',