semantic-js-mcp 0.8.1 → 0.9.0

package/protocol.mjs

@@ -125,9 +125,53 @@ export const LANGUAGE_ID = Object.freeze({
   VUE: "vue",
 });
 
+export const COMMON_VALUE = Object.freeze({
+  UNKNOWN: "unknown",
+});
+
+export const SEARCH_SCOPE = Object.freeze({
+  DOCUMENT: "document",
+});
+
+export const RUNTIME_PACKAGE = Object.freeze({
+  TYPESCRIPT: "typescript",
+});
+
 export const VUE_SCRIPT_LANGUAGE = Object.freeze({
   JAVASCRIPT: "js",
   JAVASCRIPT_REACT: "jsx",
+  TYPESCRIPT: "ts",
+  TYPESCRIPT_REACT: "tsx",
+});
+
+export const DIAGNOSTIC_PROVIDER = Object.freeze({
+  TYPESCRIPT_LANGUAGE_SERVER: "typescript-language-server",
+  VUE_LANGUAGE_SERVER: "vue-language-server",
+  UNKNOWN: COMMON_VALUE.UNKNOWN,
+});
+
+export const DIAGNOSTIC_REGION = Object.freeze({
+  DOCUMENT: SEARCH_SCOPE.DOCUMENT,
+  SCRIPT: "script",
+  SCRIPT_SETUP: "script-setup",
+  TEMPLATE: "template",
+  STYLE: "style",
+  CUSTOM_BLOCK: "custom-block",
+  UNKNOWN: COMMON_VALUE.UNKNOWN,
+});
+
+export const DIAGNOSTIC_LANGUAGE = Object.freeze({
+  TYPESCRIPT: LANGUAGE_ID.TYPESCRIPT,
+  TYPESCRIPT_REACT: LANGUAGE_ID.TYPESCRIPT_REACT,
+  JAVASCRIPT: LANGUAGE_ID.JAVASCRIPT,
+  JAVASCRIPT_REACT: LANGUAGE_ID.JAVASCRIPT_REACT,
+  VUE: LANGUAGE_ID.VUE,
+  HTML: "html",
+  PUG: "pug",
+  CSS: "css",
+  SCSS: "scss",
+  LESS: "less",
+  UNKNOWN: COMMON_VALUE.UNKNOWN,
 });
 
 export const FORBIDDEN_PUBLIC_FIELD = Object.freeze([
@@ -151,10 +195,34 @@ export const PRESENTATION_MODE = Object.freeze({
   ALL_ITEMS: "all-items",
   SUBSET: "subset",
   COUNT_ONLY: "count-only",
-  SUMMARY_BY_FILE: "summary-by-file",
+  COMPACT_SUMMARY: "compact-summary",
   PAGE: "page",
 });
 
+export const TOOL_DESCRIPTION = Object.freeze({
+  [TOOL.DOCUMENT_SYMBOLS]: `Returns declarations and nested members for one file. Use ${TOOL.DEFINITION} or ${TOOL.AUDIT_SYMBOL} with an exact position for semantic identity.`,
+  [TOOL.WORKSPACE_SYMBOLS]: `Returns declaration-shaped symbols whose names contain a query. Use ${TOOL.COUNT_NAMED_SYMBOL} or ${TOOL.AUDIT_NAMED_SYMBOL} with an exact name.`,
+  [TOOL.DEFINITION]: `Resolves definitions for one source position. Use ${TOOL.HOVER} for type information or ${TOOL.COUNT_REFERENCES} for impact scope.`,
+  [TOOL.HOVER]: `Returns inferred type information and documentation for one source position. Use ${TOOL.DEFINITION} for declaration identity.`,
+  [TOOL.DIAGNOSTICS]:
+    "Returns diagnostics for one file and marks evidence untrusted when the current document snapshot cannot be confirmed.",
+  [TOOL.COUNT_TEXT_MATCHES]: `Counts exact identifier text matches without semantic verification. Use ${TOOL.COUNT_NAMED_SYMBOL} or ${TOOL.AUDIT_NAMED_SYMBOL} to verify identity.`,
+  [TOOL.COUNT_NAMED_SYMBOL]: `Returns exact-definition and verified-reference counts for a symbol name. Use ${TOOL.AUDIT_NAMED_SYMBOL} for identity, signature, or file-hint binding verification and ${TOOL.REFERENCE_PAGE} with a returned referenceSetId for locations.`,
+  [TOOL.COUNT_REFERENCES]: `Returns verified-reference counts for the symbol at one source position. Use ${TOOL.AUDIT_SYMBOL} for identity and signature or ${TOOL.REFERENCE_PAGE} with the returned referenceSetId for locations.`,
+  [TOOL.AUDIT_NAMED_SYMBOL]: `Returns a compact exact-name audit and verifies source bindings to fileHint when no declaration is selected. Use ${TOOL.REFERENCE_PAGE} with a returned referenceSetId for locations.`,
+  [TOOL.AUDIT_SYMBOL]: `Returns a compact definition, signature, coverage, and freshness summary for one source position. Use ${TOOL.REFERENCE_PAGE} with the returned referenceSetId for locations.`,
+  [TOOL.REFERENCES]: `Returns the first page of verified source locations and detailed collection evidence. Use ${TOOL.REFERENCE_PAGE} for later pages.`,
+  [TOOL.REFERENCE_PAGE]: `Returns a page from a freshness-checked reference set created by a count, audit, or ${TOOL.REFERENCES} call.`,
+  [TOOL.UNRESOLVED_REFERENCE_PAGE]:
+    "Returns freshness-checked text-match candidates whose definitions could not be resolved, including literal failure reasons.",
+});
+
+export const LSP_METHOD = Object.freeze({
+  DOCUMENT_DIAGNOSTIC: "textDocument/diagnostic",
+  PUBLISH_DIAGNOSTICS: "textDocument/publishDiagnostics",
+  WORKSPACE_DIAGNOSTIC_REFRESH: "workspace/diagnostic/refresh",
+});
+
 export const LIMIT_MODE = Object.freeze({
   UNLIMITED: "unlimited",
   MAXIMUM: "maximum",
@@ -170,6 +238,12 @@ export const DEFINITION_MATCH = Object.freeze({
   UNRESOLVED: "unresolved",
 });
 
+export const DEFINITION_SELECTION_STATUS = Object.freeze({
+  NONE: "no-definition-selected",
+  ONE: "one-definition-selected",
+  MULTIPLE: "multiple-definitions-selected",
+});
+
 export const SIGNATURE_SOURCE = Object.freeze({
   QUERY_POSITION_HOVER: "query-position-hover",
   RESOLVED_DEFINITION_HOVER: "resolved-definition-hover",
@@ -178,6 +252,7 @@ export const SIGNATURE_SOURCE = Object.freeze({
 
 export const DIAGNOSTIC_FRESHNESS = Object.freeze({
   CURRENT: "current-document-version",
+  DIFFERENT_CONTENT: "different-document-content",
   VERSION_NOT_REPORTED: "version-not-reported-by-language-server",
   DIFFERENT_VERSION: "different-document-version",
   NOT_REPORTED_FOR_CURRENT_DOCUMENT: "not-reported-for-current-document",
@@ -198,6 +273,8 @@ export const EVIDENCE_STATUS = Object.freeze({
 
 export const DIAGNOSTIC_EVIDENCE_REASON = Object.freeze({
   CURRENT_DOCUMENT_VERSION_CONFIRMED: "current-document-version-confirmed",
+  CURRENT_DOCUMENT_SNAPSHOT_CONFIRMED: "current-document-snapshot-confirmed",
+  DOCUMENT_CONTENT_CHANGED_DURING_ACQUISITION: "document-content-changed-during-diagnostic-acquisition",
   LANGUAGE_SERVER_VERSION_NOT_REPORTED: "language-server-version-not-reported",
   LANGUAGE_SERVER_REPORTED_DIFFERENT_VERSION: "language-server-reported-different-version",
   LANGUAGE_SERVER_DID_NOT_REPORT_CURRENT_DOCUMENT: "language-server-did-not-report-current-document",
@@ -230,6 +307,10 @@ export const FINGERPRINT_ALGORITHM = Object.freeze({
   SHA_256: "sha256",
 });
 
+export const FINGERPRINT_FORMAT = Object.freeze({
+  SHA_256_PREFIX: `${FINGERPRINT_ALGORITHM.SHA_256}:`,
+});
+
 export const REFERENCE_DISCOVERY_METHOD = Object.freeze({
   OWNING_WORKSPACE_LANGUAGE_SERVER: "owning-workspace-language-server",
   DEFINITION_MATCH_FROM_ANOTHER_WORKSPACE: "definition-match-from-another-workspace",
@@ -302,10 +383,10 @@ export const INTERNAL_RESOLUTION_SOURCE = Object.freeze({
 
 export const RESULT_SCHEMA = Object.freeze({
   NAME: PRODUCT.NAME,
-  VERSION: 5,
+  VERSION: 6,
 });
 
-export const SERVER_VERSION = "0.8.1";
+export const SERVER_VERSION = "0.9.0";
 
 export const REQUIRED_RUNTIME_COMPONENT = Object.freeze({
   TYPESCRIPT_LANGUAGE_SERVER: "typescript-language-server/lib/cli.mjs",

package/scripts/agent-evaluation-contract.mjs

@@ -0,0 +1,142 @@
+import {ACCOUNTING_STATUS, CI_EXIT_CODE, CI_STATUS, COLLECTION_STATUS, DEFINITION_SELECTION_STATUS, TOOL} from "../protocol.mjs";
+
+export const AGENT_EVALUATION_ARGUMENT = Object.freeze({
+  ANSWERS: "--answers",
+});
+
+export const AGENT_EVALUATION_COVERAGE = Object.freeze({
+  COMPLETE: "complete",
+  INCOMPLETE: "incomplete",
+});
+
+export const AGENT_EVALUATION_REASON = Object.freeze({
+  ALL_DECISIONS_CORRECT: "all-decisions-correct",
+  DECISIONS_INCORRECT: "decisions-incorrect",
+  ANSWERS_INVALID: "answers-invalid",
+});
+
+export const AGENT_EVALUATION_CASES = Object.freeze([
+  Object.freeze({
+    id: "inspect-named-symbol-identity",
+    question: "Which tool should inspect identity and signature before changing this named symbol?",
+    compactResult: Object.freeze({
+      tool: TOOL.COUNT_NAMED_SYMBOL,
+      result: Object.freeze({
+        requestedSymbol: "calculateTotal",
+        exactDefinitionsFound: 1,
+        definitionSelectionStatus: DEFINITION_SELECTION_STATUS.ONE,
+        references: Object.freeze({verifiedTotal: 18}),
+        unresolvedReferences: Object.freeze({count: 0}),
+      }),
+      collection: Object.freeze({status: COLLECTION_STATUS.COMPLETE, stoppedByLimit: false}),
+      continueWith: Object.freeze([TOOL.AUDIT_NAMED_SYMBOL, TOOL.REFERENCE_PAGE]),
+    }),
+    expected: Object.freeze({nextTool: TOOL.AUDIT_NAMED_SYMBOL, coverage: AGENT_EVALUATION_COVERAGE.COMPLETE}),
+  }),
+  Object.freeze({
+    id: "inspect-unresolved-references",
+    question: "Which tool should inspect the unresolved candidates before claiming full impact coverage?",
+    compactResult: Object.freeze({
+      tool: TOOL.AUDIT_NAMED_SYMBOL,
+      result: Object.freeze({
+        requestedSymbol: "RequestHandler",
+        exactDefinitionsFound: 1,
+        references: Object.freeze({verifiedTotal: 52}),
+        unresolvedReferences: Object.freeze({count: 1}),
+      }),
+      collection: Object.freeze({status: COLLECTION_STATUS.PARTIAL, stoppedByLimit: false}),
+      continueWith: Object.freeze([TOOL.UNRESOLVED_REFERENCE_PAGE, TOOL.REFERENCE_PAGE]),
+    }),
+    expected: Object.freeze({nextTool: TOOL.UNRESOLVED_REFERENCE_PAGE, coverage: AGENT_EVALUATION_COVERAGE.INCOMPLETE}),
+  }),
+  Object.freeze({
+    id: "disambiguate-homonymous-definitions",
+    question: "Which tool should identify the intended declaration from an exact source position?",
+    compactResult: Object.freeze({
+      tool: TOOL.COUNT_NAMED_SYMBOL,
+      result: Object.freeze({
+        requestedSymbol: "createClient",
+        exactDefinitionsFound: 3,
+        definitionSelectionStatus: DEFINITION_SELECTION_STATUS.MULTIPLE,
+        unresolvedReferences: Object.freeze({count: 0}),
+      }),
+      collection: Object.freeze({status: COLLECTION_STATUS.COMPLETE, stoppedByLimit: false}),
+      continueWith: Object.freeze([TOOL.AUDIT_SYMBOL, TOOL.AUDIT_NAMED_SYMBOL]),
+    }),
+    expected: Object.freeze({nextTool: TOOL.AUDIT_SYMBOL, coverage: AGENT_EVALUATION_COVERAGE.COMPLETE}),
+  }),
+  Object.freeze({
+    id: "reuse-file-hint-binding-position",
+    question: "Which tool should reuse the verified source position without inventing a filename declaration?",
+    compactResult: Object.freeze({
+      tool: TOOL.AUDIT_NAMED_SYMBOL,
+      result: Object.freeze({
+        requestedSymbol: "RenamedPanel",
+        exactDefinitionsFound: 0,
+        definitionSelectionStatus: DEFINITION_SELECTION_STATUS.NONE,
+        fileHintResolution: Object.freeze({
+          textMatchesFound: 2,
+          textMatchesChecked: 2,
+          textMatchesResolvingToFileFilter: 2,
+          textMatchesWhoseDefinitionCouldNotBeResolved: 0,
+          accountingStatus: ACCOUNTING_STATUS.COMPLETE,
+          sourcePositionForAudit: Object.freeze({file: "src/Parent.vue", line: 2, column: 8}),
+        }),
+      }),
+      collection: Object.freeze({status: COLLECTION_STATUS.COMPLETE, stoppedByLimit: false}),
+      continueWith: Object.freeze([TOOL.AUDIT_SYMBOL]),
+    }),
+    expected: Object.freeze({nextTool: TOOL.AUDIT_SYMBOL, coverage: AGENT_EVALUATION_COVERAGE.COMPLETE}),
+  }),
+]);
+
+function publicCase(evaluationCase) {
+  return {
+    id: evaluationCase.id,
+    question: evaluationCase.question,
+    compactResult: evaluationCase.compactResult,
+  };
+}
+
+export function evaluationPrompt() {
+  return {
+    instructions: "For each case, choose one exact tool from continueWith and classify collection coverage as complete or incomplete.",
+    answerFormat: {
+      answers: "array with one object per case",
+      answer: {
+        id: "exact case id",
+        nextTool: "one exact tool from that case's continueWith list",
+        coverage: {enum: Object.values(AGENT_EVALUATION_COVERAGE)},
+      },
+    },
+    cases: AGENT_EVALUATION_CASES.map(publicCase),
+  };
+}
+
+export function gradeAgentAnswers(input) {
+  const suppliedAnswers = Array.isArray(input?.answers) ? input.answers : [];
+  const answerById = new Map(suppliedAnswers.map((answer) => [answer.id, answer]));
+  const cases = AGENT_EVALUATION_CASES.map((evaluationCase) => {
+    const answer = answerById.get(evaluationCase.id);
+    const nextToolCorrect = answer?.nextTool === evaluationCase.expected.nextTool;
+    const coverageCorrect = answer?.coverage === evaluationCase.expected.coverage;
+    return {
+      id: evaluationCase.id,
+      correct: nextToolCorrect && coverageCorrect,
+      nextToolCorrect,
+      coverageCorrect,
+    };
+  });
+  const correctCases = cases.filter((item) => item.correct).length;
+  const complete = suppliedAnswers.length === AGENT_EVALUATION_CASES.length && correctCases === AGENT_EVALUATION_CASES.length;
+  const status = complete ? CI_STATUS.PASS : CI_STATUS.FAIL;
+  return {
+    status,
+    exitCode: CI_EXIT_CODE[status.toUpperCase()],
+    reason: complete ? AGENT_EVALUATION_REASON.ALL_DECISIONS_CORRECT : AGENT_EVALUATION_REASON.DECISIONS_INCORRECT,
+    casesAvailable: AGENT_EVALUATION_CASES.length,
+    answersSupplied: suppliedAnswers.length,
+    correctCases,
+    cases,
+  };
+}

package/scripts/agent-evaluation-smoke.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import {CI_STATUS} from "../protocol.mjs";
+import {AGENT_EVALUATION_CASES, evaluationPrompt, gradeAgentAnswers} from "./agent-evaluation-contract.mjs";
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const prompt = evaluationPrompt();
+assert(prompt.cases.length === AGENT_EVALUATION_CASES.length, "Evaluation prompt omitted cases");
+assert(
+  prompt.cases.every((item) => !("expected" in item)),
+  "Evaluation prompt exposed expected answers",
+);
+
+const correctAnswers = {
+  answers: AGENT_EVALUATION_CASES.map((evaluationCase) => ({id: evaluationCase.id, ...evaluationCase.expected})),
+};
+const passing = gradeAgentAnswers(correctAnswers);
+assert(passing.status === CI_STATUS.PASS, "Correct agent answers did not pass");
+assert(passing.correctCases === AGENT_EVALUATION_CASES.length, "Correct answer count was wrong");
+
+const incorrectAnswers = {
+  answers: correctAnswers.answers.map((answer, index) =>
+    index === 0 ? {...answer, nextTool: AGENT_EVALUATION_CASES[1].expected.nextTool} : answer,
+  ),
+};
+const failing = gradeAgentAnswers(incorrectAnswers);
+assert(failing.status === CI_STATUS.FAIL, "Incorrect agent answer did not fail");
+assert(failing.correctCases === AGENT_EVALUATION_CASES.length - 1, "Incorrect answer count was wrong");
+
+process.stdout.write(
+  `${JSON.stringify(
+    {
+      evaluationCases: AGENT_EVALUATION_CASES.length,
+      hiddenExpectedAnswers: "ok",
+      deterministicGrading: "ok",
+      incorrectDecisionRejected: "ok",
+    },
+    null,
+    2,
+  )}\n`,
+);

package/scripts/agent-evaluation.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+
+import {readFile} from "node:fs/promises";
+import {parse as parseYaml, stringify as stringifyYaml} from "yaml";
+import {CI_EXIT_CODE, CI_STATUS, CLI_ARGUMENT} from "../protocol.mjs";
+import {AGENT_EVALUATION_ARGUMENT, AGENT_EVALUATION_REASON, evaluationPrompt, gradeAgentAnswers} from "./agent-evaluation-contract.mjs";
+
+const answersArgumentIndex = process.argv.indexOf(AGENT_EVALUATION_ARGUMENT.ANSWERS);
+const answersFile = answersArgumentIndex >= 0 ? process.argv[answersArgumentIndex + 1] : undefined;
+const useYaml = process.argv.includes(CLI_ARGUMENT.YAML);
+
+let output;
+if (!answersFile) {
+  output = evaluationPrompt();
+} else {
+  try {
+    const text = await readFile(answersFile, "utf8");
+    let answers;
+    try {
+      answers = JSON.parse(text);
+    } catch {
+      answers = parseYaml(text);
+    }
+    output = gradeAgentAnswers(answers);
+    process.exitCode = output.exitCode;
+  } catch (error) {
+    output = {
+      status: CI_STATUS.BLOCKED,
+      exitCode: CI_EXIT_CODE.BLOCKED,
+      reason: AGENT_EVALUATION_REASON.ANSWERS_INVALID,
+      message: error instanceof Error ? error.message : String(error),
+    };
+    process.exitCode = output.exitCode;
+  }
+}
+
+process.stdout.write(useYaml ? stringifyYaml(output, {lineWidth: 0}) : `${JSON.stringify(output, null, 2)}\n`);

package/scripts/check-protocol-literals.mjs

@@ -11,13 +11,18 @@ import {
   CLI_ARGUMENT,
   CLI_COMMAND,
   CLI_MESSAGE,
+  COMMON_VALUE,
   CONFIGURATION_FILE,
   CONTENT_FRESHNESS,
   DEFAULT,
   DEFINITION_MATCH,
   DEFINITION_RESOLUTION_METHOD,
+  DEFINITION_SELECTION_STATUS,
   DIAGNOSTIC_EVIDENCE_REASON,
   DIAGNOSTIC_FRESHNESS,
+  DIAGNOSTIC_LANGUAGE,
+  DIAGNOSTIC_PROVIDER,
+  DIAGNOSTIC_REGION,
   DIAGNOSTIC_SEVERITY,
   DOCTOR_CHECK,
   DOCTOR_DISTRIBUTION_ACCEPTED_STATUS,
@@ -28,8 +33,10 @@ import {
   ERROR_CODE,
   EVIDENCE_TYPE,
   FINGERPRINT_ALGORITHM,
+  FINGERPRINT_FORMAT,
   INTERNAL_RESOLUTION_SOURCE,
   LIMIT_MODE,
+  LSP_METHOD,
   NODE_EVENT,
   PRESENTATION_MODE,
   PACKAGE_PATH,
@@ -38,10 +45,13 @@ import {
   REFERENCE_SET_CHANGE_TYPE,
   REQUIRED_RUNTIME_COMPONENT,
   RUNTIME_COMMAND,
+  RUNTIME_PACKAGE,
   RUNTIME_REQUIREMENT,
   RUNTIME_REQUIREMENT_KIND,
   RESULT_SCHEMA,
+  SEARCH_SCOPE,
   TOOL,
+  TOOL_DESCRIPTION,
   TYPESCRIPT_PROJECT_KIND,
   SOURCE_EXCLUDED_GLOBS,
   SOURCE_FILE_GLOBS,
@@ -68,13 +78,21 @@ if (semanticServer?.tool_timeout_sec !== DEFAULT.MCP_TOOL_TIMEOUT_SECONDS) {
   throw new Error(".mcp.json tool_timeout_sec differs from protocol.mjs");
 }
 const groups = [
+  COMMON_VALUE,
+  SEARCH_SCOPE,
+  RUNTIME_PACKAGE,
   TOOL,
+  TOOL_DESCRIPTION,
   COLLECTION_STATUS,
   PRESENTATION_MODE,
   LIMIT_MODE,
   ACCOUNTING_STATUS,
   DEFINITION_MATCH,
+  DEFINITION_SELECTION_STATUS,
   DIAGNOSTIC_FRESHNESS,
+  DIAGNOSTIC_PROVIDER,
+  DIAGNOSTIC_REGION,
+  DIAGNOSTIC_LANGUAGE,
   DIAGNOSTIC_SEVERITY,
   DIAGNOSTIC_EVIDENCE_REASON,
   EVIDENCE_STATUS,
@@ -82,10 +100,12 @@ const groups = [
   ERROR_CODE,
   EVIDENCE_TYPE,
   FINGERPRINT_ALGORITHM,
+  FINGERPRINT_FORMAT,
   REFERENCE_DISCOVERY_METHOD,
   REFERENCE_SET_CHANGE_TYPE,
   DEFINITION_RESOLUTION_METHOD,
   INTERNAL_RESOLUTION_SOURCE,
+  LSP_METHOD,
   UNRESOLVED_REFERENCE_REASON,
   TYPESCRIPT_PROJECT_KIND,
   CI_STATUS,

package/scripts/ci-smoke.mjs

@@ -51,8 +51,7 @@ async function evaluate(name, input, expectedStatus, expectedExitCode) {
 
 function canonicalResult(tool, collectionStatus, result, extra = {}) {
   return {
-    server: {name: PRODUCT.NAME, version: SERVER_VERSION},
-    resultSchema: {name: RESULT_SCHEMA.NAME, version: RESULT_SCHEMA.VERSION},
+    producer: {name: PRODUCT.NAME, version: SERVER_VERSION, resultSchemaVersion: RESULT_SCHEMA.VERSION},
     tool,
     request: {},
     result,
@@ -109,7 +108,23 @@ try {
     "wrong-result-schema-version",
     {
       ...canonicalResult(TOOL.COUNT_REFERENCES, COLLECTION_STATUS.COMPLETE, {}),
-      resultSchema: {name: RESULT_SCHEMA.NAME, version: RESULT_SCHEMA.VERSION + 1},
+      producer: {name: PRODUCT.NAME, version: SERVER_VERSION, resultSchemaVersion: RESULT_SCHEMA.VERSION + 1},
+    },
+    CI_STATUS.BLOCKED,
+    CI_EXIT_CODE.BLOCKED,
+  );
+
+  await evaluate(
+    "schema-5-envelope",
+    {
+      server: {name: PRODUCT.NAME, version: SERVER_VERSION},
+      resultSchema: {name: RESULT_SCHEMA.NAME, version: RESULT_SCHEMA.VERSION - 1},
+      tool: TOOL.COUNT_REFERENCES,
+      request: {},
+      result: {},
+      collection: {status: COLLECTION_STATUS.COMPLETE},
+      presentation: {mode: PRESENTATION_MODE.COUNT_ONLY},
+      continueWith: [{tool: TOOL.AUDIT_SYMBOL}],
     },
     CI_STATUS.BLOCKED,
     CI_EXIT_CODE.BLOCKED,
@@ -136,7 +151,7 @@ try {
     "unknown-continuation-tool",
     {
       ...canonicalResult(TOOL.COUNT_REFERENCES, COLLECTION_STATUS.COMPLETE, {}),
-      continueWith: [{tool: "unknown_tool"}],
+      continueWith: ["unknown_tool"],
     },
     CI_STATUS.BLOCKED,
     CI_EXIT_CODE.BLOCKED,

package/scripts/codex-plugin-verification.mjs

@@ -0,0 +1,129 @@
+import {mkdir} from "node:fs/promises";
+import path from "node:path";
+import {CI_EXIT_CODE, CI_STATUS, NODE_EVENT, PRODUCT} from "../protocol.mjs";
+import {CODEX_DISTRIBUTION} from "./distribution-policy.mjs";
+import {RELEASE_CHECK, RELEASE_REASON} from "./release-contract.mjs";
+
+function check(name, status, reason, details) {
+  return {name, status, reason, ...(details ? {details} : {})};
+}
+
+function run(command, args, options) {
+  return new Promise((resolve) => {
+    const child = options.spawn(command, args, {cwd: options.cwd, env: options.env, stdio: ["ignore", "pipe", "pipe"]});
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on("data", (chunk) => stdout.push(chunk));
+    child.stderr.on("data", (chunk) => stderr.push(chunk));
+    child.on(NODE_EVENT.ERROR, (error) => resolve({exitCode: undefined, stdout: "", stderr: error.message}));
+    child.on(NODE_EVENT.CLOSE, (exitCode) =>
+      resolve({exitCode, stdout: Buffer.concat(stdout).toString("utf8"), stderr: Buffer.concat(stderr).toString("utf8")}),
+    );
+  });
+}
+
+function failureMessage(result) {
+  return result.stderr.trim() || result.stdout.trim();
+}
+
+function networkUnavailable(result) {
+  const message = `${result.stdout}\n${result.stderr}`.toLowerCase();
+  return CODEX_DISTRIBUTION.NETWORK_UNAVAILABLE_TEXT.some((text) => message.includes(text.toLowerCase()));
+}
+
+export async function verifyCodexPlugin({version, workspace, spawn, runCommand}) {
+  const codexHome = path.join(workspace, CODEX_DISTRIBUTION.HOME_DIRECTORY);
+  await mkdir(codexHome, {recursive: true});
+  const environment = {...process.env, [CODEX_DISTRIBUTION.HOME_ENVIRONMENT_VARIABLE]: codexHome};
+  const execute = runCommand
+    ? (command, args) => runCommand(command, args, {cwd: workspace, env: environment})
+    : (command, args) => run(command, args, {cwd: workspace, env: environment, spawn});
+  const marketplaceRef = `${CODEX_DISTRIBUTION.VERSION_REF_PREFIX}${version}`;
+
+  const marketplace = await execute(CODEX_DISTRIBUTION.EXECUTABLE, [
+    CODEX_DISTRIBUTION.PLUGIN_COMMAND,
+    CODEX_DISTRIBUTION.MARKETPLACE_COMMAND,
+    CODEX_DISTRIBUTION.ADD_COMMAND,
+    CODEX_DISTRIBUTION.MARKETPLACE_SOURCE,
+    CODEX_DISTRIBUTION.REF_ARGUMENT,
+    marketplaceRef,
+    CODEX_DISTRIBUTION.JSON_ARGUMENT,
+  ]);
+  if (marketplace.exitCode === undefined) {
+    return [
+      check(RELEASE_CHECK.CODEX_MARKETPLACE, CI_STATUS.BLOCKED, RELEASE_REASON.CODEX_CLI_UNAVAILABLE, {
+        message: failureMessage(marketplace),
+      }),
+    ];
+  }
+  if (marketplace.exitCode !== CI_EXIT_CODE.PASS) {
+    const unavailable = networkUnavailable(marketplace);
+    return [
+      check(
+        RELEASE_CHECK.CODEX_MARKETPLACE,
+        unavailable ? CI_STATUS.BLOCKED : CI_STATUS.FAIL,
+        unavailable ? RELEASE_REASON.CODEX_MARKETPLACE_UNAVAILABLE : RELEASE_REASON.CODEX_MARKETPLACE_FAILED,
+        {
+          marketplaceRef,
+          message: failureMessage(marketplace),
+        },
+      ),
+    ];
+  }
+
+  const checks = [check(RELEASE_CHECK.CODEX_MARKETPLACE, CI_STATUS.PASS, RELEASE_REASON.CHECK_COMPLETED, {marketplaceRef})];
+  const installation = await execute(CODEX_DISTRIBUTION.EXECUTABLE, [
+    CODEX_DISTRIBUTION.PLUGIN_COMMAND,
+    CODEX_DISTRIBUTION.ADD_COMMAND,
+    CODEX_DISTRIBUTION.PLUGIN_SELECTOR,
+    CODEX_DISTRIBUTION.JSON_ARGUMENT,
+  ]);
+  if (installation.exitCode !== CI_EXIT_CODE.PASS) {
+    const unavailable = installation.exitCode === undefined || networkUnavailable(installation);
+    checks.push(
+      check(
+        RELEASE_CHECK.CODEX_PLUGIN_INSTALLATION,
+        unavailable ? CI_STATUS.BLOCKED : CI_STATUS.FAIL,
+        unavailable ? RELEASE_REASON.CODEX_PLUGIN_SOURCE_UNAVAILABLE : RELEASE_REASON.CODEX_PLUGIN_INSTALLATION_FAILED,
+        {message: failureMessage(installation)},
+      ),
+    );
+    return checks;
+  }
+
+  const listed = await execute(CODEX_DISTRIBUTION.EXECUTABLE, [
+    CODEX_DISTRIBUTION.PLUGIN_COMMAND,
+    CODEX_DISTRIBUTION.LIST_COMMAND,
+    CODEX_DISTRIBUTION.JSON_ARGUMENT,
+  ]);
+  let listResult;
+  try {
+    listResult = JSON.parse(listed.stdout);
+  } catch {
+    listResult = undefined;
+  }
+  const installedPlugin = listResult?.installed?.find(
+    (plugin) => plugin.name === PRODUCT.NAME && plugin.marketplaceName === CODEX_DISTRIBUTION.MARKETPLACE_NAME,
+  );
+  if (listed.exitCode === undefined || networkUnavailable(listed)) {
+    checks.push(
+      check(RELEASE_CHECK.CODEX_PLUGIN_INSTALLATION, CI_STATUS.BLOCKED, RELEASE_REASON.CODEX_PLUGIN_SOURCE_UNAVAILABLE, {
+        message: failureMessage(listed),
+      }),
+    );
+    return checks;
+  }
+  const installedVersionMatches =
+    listed.exitCode === CI_EXIT_CODE.PASS && installedPlugin?.version === version && installedPlugin?.enabled === true;
+  checks.push(
+    check(
+      RELEASE_CHECK.CODEX_PLUGIN_INSTALLATION,
+      installedVersionMatches ? CI_STATUS.PASS : CI_STATUS.FAIL,
+      installedVersionMatches ? RELEASE_REASON.CHECK_COMPLETED : RELEASE_REASON.CODEX_PLUGIN_VERSION_DIFFERENT,
+      installedVersionMatches
+        ? {version}
+        : {expectedVersion: version, installedVersion: installedPlugin?.version, message: failureMessage(listed)},
+    ),
+  );
+  return checks;
+}

package/scripts/distribution-policy.mjs

@@ -19,6 +19,34 @@ export const NPM_AUTOMATIC_PACKAGE_FILE = Object.freeze([
   REQUIRED_PACKAGE_FILE.LICENSE,
 ]);
 
+export const CODEX_DISTRIBUTION = Object.freeze({
+  EXECUTABLE: "codex",
+  HOME_ENVIRONMENT_VARIABLE: "CODEX_HOME",
+  MARKETPLACE_NAME: "elnonathan",
+  MARKETPLACE_SOURCE: "elnonathan/semantic-js-mcp",
+  PLUGIN_SELECTOR: "semantic-js-mcp@elnonathan",
+  VERSION_REF_PREFIX: "v",
+  HOME_DIRECTORY: "codex-home",
+  PLUGIN_COMMAND: "plugin",
+  MARKETPLACE_COMMAND: "marketplace",
+  ADD_COMMAND: "add",
+  LIST_COMMAND: "list",
+  REF_ARGUMENT: "--ref",
+  JSON_ARGUMENT: "--json",
+  NETWORK_UNAVAILABLE_TEXT: Object.freeze([
+    "Could not resolve host",
+    "failed to lookup address information",
+    "network is unreachable",
+    "network timeout",
+    "timed out",
+    "unable to access",
+  ]),
+});
+
+export const NPM_DISTRIBUTION = Object.freeze({
+  CACHE_ENVIRONMENT_VARIABLE: "npm_config_cache",
+});
+
 const WINDOWS_PLATFORM = "win32";
 const WINDOWS_COMMAND_SUFFIX = ".cmd";
 const DEPENDENCY_DIRECTORY_PREFIX = "node_modules/";

package/scripts/distribution-smoke.mjs

@@ -16,6 +16,7 @@ import {
 } from "../protocol.mjs";
 import {
   REQUIRED_PACKAGE_FILE,
+  NPM_DISTRIBUTION,
   allProductionDependenciesAreBundled,
   npmExecutableName,
   packagePathIsAllowed,
@@ -27,7 +28,7 @@ const packageOutput = path.join(workspace, "package");
 const consumer = path.join(workspace, "consumer");
 const npmCache = path.join(workspace, "npm-cache");
 const npmCli = process.env.npm_execpath;
-const npmEnvironment = {...process.env, npm_config_cache: npmCache};
+const npmEnvironment = {...process.env, [NPM_DISTRIBUTION.CACHE_ENVIRONMENT_VARIABLE]: npmCache};
 
 function run(command, args, options = {}) {
   return new Promise((resolve, reject) => {