semantic-js-mcp 0.8.1 → 0.10.0

package/lib/doctor.mjs

@@ -1,5 +1,5 @@
 import path from "node:path";
-import {mkdtemp, mkdir, realpath, rm, writeFile} from "node:fs/promises";
+import {mkdtemp, mkdir, realpath, writeFile} from "node:fs/promises";
 import {tmpdir} from "node:os";
 import {Client} from "@modelcontextprotocol/sdk/client/index.js";
 import {StdioClientTransport} from "@modelcontextprotocol/sdk/client/stdio.js";
@@ -24,6 +24,7 @@ import {
   TOOL_ORDER,
 } from "../protocol.mjs";
 import {PACKAGE_ROOT, inspectExternalCommand, inspectNodeRuntime, inspectRuntimeComponents} from "./runtime.mjs";
+import {removeTemporaryDirectory} from "./temporary-directory.mjs";
 
 const STATUS_EXIT_CODE = Object.freeze({
   [CI_STATUS.PASS]: CI_EXIT_CODE.PASS,
@@ -312,7 +313,7 @@ export async function runDoctor({packageRoot = PACKAGE_ROOT} = {}) {
     }
   } finally {
     await client.close().catch(() => undefined);
-    await rm(fixture.workspace, {recursive: true, force: true});
+    await removeTemporaryDirectory(fixture.workspace);
   }
 
   return doctorResult(packageRoot, checks, runtime);

package/lib/file-identity.mjs

@@ -0,0 +1,18 @@
+import path from "node:path";
+import {OPERATING_SYSTEM} from "../protocol.mjs";
+
+export function fileIdentity(file, operatingSystem = process.platform) {
+  const pathImplementation = operatingSystem === OPERATING_SYSTEM.WINDOWS ? path.win32 : path;
+  const resolved = pathImplementation.resolve(file);
+  return operatingSystem === OPERATING_SYSTEM.WINDOWS ? resolved.toLowerCase() : resolved;
+}
+
+export function locationKeyAt(file, line, column, operatingSystem = process.platform) {
+  return `${fileIdentity(file, operatingSystem)}:${line}:${column}`;
+}
+
+export function locationKeyForOperatingSystem(operatingSystem) {
+  return (location) => locationKeyAt(location.file, location.range.start.line, location.range.start.column, operatingSystem);
+}
+
+export const locationKey = locationKeyForOperatingSystem(process.platform);

package/lib/pending-requests.mjs

@@ -0,0 +1,38 @@
+export class PendingRequestRegistry {
+  constructor({timeoutMilliseconds, timeoutMessage}) {
+    this.timeoutMilliseconds = timeoutMilliseconds;
+    this.timeoutMessage = timeoutMessage;
+    this.entries = new Map();
+  }
+
+  get size() {
+    return this.entries.size;
+  }
+
+  create(key, operation) {
+    if (this.entries.has(key)) throw new Error(`Pending request already exists: ${key}`);
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.entries.delete(key);
+        reject(new Error(this.timeoutMessage(operation)));
+      }, this.timeoutMilliseconds);
+      this.entries.set(key, {resolve, reject, timer});
+    });
+  }
+
+  take(key) {
+    const entry = this.entries.get(key);
+    if (!entry) return undefined;
+    clearTimeout(entry.timer);
+    this.entries.delete(key);
+    return entry;
+  }
+
+  rejectAll(error) {
+    for (const entry of this.entries.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(error);
+    }
+    this.entries.clear();
+  }
+}

package/lib/runtime.mjs

@@ -5,6 +5,8 @@ import path from "node:path";
 import {fileURLToPath} from "node:url";
 import {CONFIGURATION_FILE, NODE_EVENT, PROCESS_EXIT_CODE, REQUIRED_RUNTIME_COMPONENT, RUNTIME_REQUIREMENT} from "../protocol.mjs";
 
+const STREAM_EVENT = Object.freeze({DATA: "data"});
+
 export const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 
 export function inspectNodeRuntime() {
@@ -50,10 +52,10 @@ export function inspectExternalCommand(command, args) {
     const child = spawn(command, args, {stdio: ["ignore", "pipe", "pipe"]});
     let stdout = "";
     let stderr = "";
-    child.stdout.on("data", (chunk) => {
+    child.stdout.on(STREAM_EVENT.DATA, (chunk) => {
       stdout += chunk;
     });
-    child.stderr.on("data", (chunk) => {
+    child.stderr.on(STREAM_EVENT.DATA, (chunk) => {
       stderr += chunk;
     });
     child.on(NODE_EVENT.ERROR, (error) => resolve({command, available: false, error: error.message}));

package/lib/semantic-evidence.mjs

@@ -0,0 +1,44 @@
+import {
+  COLLECTION_STATUS,
+  DEFINITION_SELECTION_STATUS,
+  SEMANTIC_EVIDENCE_FOLLOW_UP_REASON,
+  SEMANTIC_EVIDENCE_STATUS,
+  TOOL,
+} from "../protocol.mjs";
+
+const NAMED_SYMBOL_TOOLS = new Set([TOOL.COUNT_NAMED_SYMBOL, TOOL.AUDIT_NAMED_SYMBOL]);
+const DEFINITION_SELECTION_STATUSES = new Set(Object.values(DEFINITION_SELECTION_STATUS));
+
+export function isNamedSymbolTool(tool) {
+  return NAMED_SYMBOL_TOOLS.has(tool);
+}
+
+export function namedSemanticEvidence(selectionStatus, collectionStatus) {
+  const followUpReasons = [];
+  if (collectionStatus === COLLECTION_STATUS.LIMITED) {
+    followUpReasons.push(SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.COLLECTION_LIMITED);
+  }
+  if (collectionStatus === COLLECTION_STATUS.PARTIAL) {
+    followUpReasons.push(SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.COLLECTION_PARTIAL);
+  }
+  if (selectionStatus === DEFINITION_SELECTION_STATUS.NONE) {
+    followUpReasons.push(SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.NO_DEFINITION_SELECTED);
+  }
+  if (selectionStatus === DEFINITION_SELECTION_STATUS.MULTIPLE) {
+    followUpReasons.push(SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.MULTIPLE_DEFINITIONS_SELECTED);
+  }
+  return {
+    status: followUpReasons.length === 0 ? SEMANTIC_EVIDENCE_STATUS.USABLE : SEMANTIC_EVIDENCE_STATUS.FOLLOW_UP_REQUIRED,
+    followUpReasons,
+  };
+}
+
+export function namedSemanticEvidenceMatches(result, collectionStatus) {
+  const actual = result?.semanticEvidence;
+  if (!actual || !Array.isArray(actual.followUpReasons)) return false;
+  if (!DEFINITION_SELECTION_STATUSES.has(result.definitionSelectionStatus)) return false;
+  const expected = namedSemanticEvidence(result.definitionSelectionStatus, collectionStatus);
+  if (actual.status !== expected.status) return false;
+  if (actual.followUpReasons.length !== expected.followUpReasons.length) return false;
+  return actual.followUpReasons.every((reason, index) => reason === expected.followUpReasons[index]);
+}

package/lib/stable-collection.mjs

@@ -0,0 +1,10 @@
+export async function collectStableSnapshot({attempts, collect, inventory, sameInventory, fingerprint}) {
+  for (let attempt = 1; attempt <= attempts; attempt++) {
+    const inventoryBefore = await inventory();
+    const value = await collect();
+    const [fingerprints, inventoryAfter] = await Promise.all([fingerprint(value), inventory()]);
+    if (!sameInventory(inventoryBefore, inventoryAfter)) continue;
+    return {value, fingerprints, inventory: inventoryAfter, attempt};
+  }
+  return undefined;
+}

package/lib/temporary-directory.mjs

@@ -0,0 +1,15 @@
+import {rm} from "node:fs/promises";
+
+const CLEANUP = Object.freeze({
+  MAXIMUM_RETRIES: 10,
+  RETRY_DELAY_MILLISECONDS: 100,
+});
+
+export async function removeTemporaryDirectory(directory) {
+  await rm(directory, {
+    recursive: true,
+    force: true,
+    maxRetries: CLEANUP.MAXIMUM_RETRIES,
+    retryDelay: CLEANUP.RETRY_DELAY_MILLISECONDS,
+  });
+}

package/package.json

@@ -1,7 +1,19 @@
 {
   "name": "semantic-js-mcp",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Semantic understanding of JavaScript codebases for AI agents",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "lsp",
+    "language-server-protocol",
+    "javascript",
+    "typescript",
+    "vue",
+    "semantic-analysis",
+    "code-navigation",
+    "ai-agents"
+  ],
   "author": {
     "name": "Jonathan Muñoz Lucas",
     "email": "git@jonathanmunoz.dev",
@@ -32,17 +44,29 @@
     "node": ">=22"
   },
   "scripts": {
-    "check": "npm run format:check && node --check protocol.mjs && node --check server.mjs && node --check cli.mjs && node --check lib/runtime.mjs && node --check lib/doctor.mjs && node --check scripts/generate-protocol-reference.mjs && node --check scripts/check-protocol-literals.mjs && node --check scripts/check-runtime.mjs && node --check scripts/semantic-js-mcp-ci.mjs && node --check scripts/ci-smoke.mjs && node --check scripts/smoke.mjs && node --check scripts/vue-smoke.mjs && node --check scripts/benchmark.mjs && node --check scripts/distribution-policy.mjs && node --check scripts/distribution-smoke.mjs && node scripts/generate-protocol-reference.mjs --check && node scripts/check-protocol-literals.mjs",
+    "check": "npm run format:check && node --check protocol.mjs && node --check server.mjs && node --check cli.mjs && node --check lib/runtime.mjs && node --check lib/doctor.mjs && node --check lib/semantic-evidence.mjs && node --check lib/pending-requests.mjs && node --check lib/stable-collection.mjs && node --check scripts/generate-protocol-reference.mjs && node --check scripts/check-protocol-literals.mjs && node --check scripts/check-runtime.mjs && node --check scripts/documentation-contract.mjs && node --check scripts/documentation-gate.mjs && node --check scripts/documentation-gate-smoke.mjs && node --check scripts/semantic-js-mcp-ci.mjs && node --check scripts/ci-smoke.mjs && node --check scripts/negative-verification-smoke.mjs && node --check scripts/doctor-smoke.mjs && node --check scripts/smoke.mjs && node --check scripts/vue-smoke.mjs && node --check scripts/lifecycle-smoke.mjs && node --check scripts/lifecycle-memory-contract.mjs && node --check scripts/lifecycle-memory-observer.mjs && node --check scripts/lifecycle-memory-benchmark.mjs && node --check scripts/benchmark.mjs && node --check scripts/distribution-policy.mjs && node --check scripts/distribution-smoke.mjs && node --check scripts/release-contract.mjs && node --check scripts/release-verify.mjs && node --check scripts/release-smoke.mjs && node --check scripts/postpublication-smoke.mjs && node --check scripts/codex-plugin-verification.mjs && node --check scripts/agent-evaluation-contract.mjs && node --check scripts/agent-evaluation.mjs && node --check scripts/agent-evaluation-smoke.mjs && node --check scripts/repository-matrix-contract.mjs && node --check scripts/repository-matrix.mjs && node --check scripts/repository-matrix-smoke.mjs && node scripts/generate-protocol-reference.mjs --check && node scripts/check-protocol-literals.mjs && node scripts/documentation-gate-smoke.mjs",
     "check:runtime": "node scripts/check-runtime.mjs",
+    "check:documentation": "node scripts/documentation-gate.mjs",
     "doctor": "node cli.mjs doctor",
     "ci:evaluate": "node scripts/semantic-js-mcp-ci.mjs",
     "smoke": "node scripts/smoke.mjs",
     "smoke:ci": "node scripts/ci-smoke.mjs",
+    "smoke:negative": "node scripts/negative-verification-smoke.mjs",
+    "smoke:doctor": "node scripts/doctor-smoke.mjs",
     "smoke:vue": "node scripts/vue-smoke.mjs",
+    "smoke:lifecycle": "node scripts/lifecycle-smoke.mjs",
     "smoke:distribution": "node scripts/distribution-smoke.mjs",
+    "smoke:release": "node scripts/release-smoke.mjs",
+    "smoke:evaluation": "node scripts/agent-evaluation-smoke.mjs",
+    "smoke:matrix": "node scripts/repository-matrix-smoke.mjs",
+    "evaluate:agent": "node scripts/agent-evaluation.mjs",
+    "validate:repositories": "node scripts/repository-matrix.mjs",
+    "release:verify": "node scripts/release-verify.mjs",
+    "verify:published": "node scripts/postpublication-smoke.mjs",
     "benchmark": "node scripts/benchmark.mjs",
-    "format": "prettier --write \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\"",
-    "format:check": "prettier --check \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\""
+    "benchmark:lifecycle-memory": "node scripts/lifecycle-memory-benchmark.mjs",
+    "format": "prettier --write \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".github/**/*.yml\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\"",
+    "format:check": "prettier --check \".codex-plugin/**/*.json\" \".agents/plugins/marketplace.json\" \".github/**/*.yml\" \".mcp.json\" \".prettierrc.json\" \"package.json\" \"package-lock.json\" \"CHANGELOG.md\" \"CONTRIBUTING.md\" \"README.md\" \"ROADMAP.md\" \"SECURITY.md\" \"*.mjs\" \"docs/**/*.md\" \"lib/**/*.mjs\" \"scripts/**/*.mjs\" \"skills/**/SKILL.md\" \"skills/**/agents/*.yaml\""
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",

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,43 @@ 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 plus explicit semantic follow-up status 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 with explicit semantic follow-up status 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",
+  EXECUTE_COMMAND: "workspace/executeCommand",
+  PUBLISH_DIAGNOSTICS: "textDocument/publishDiagnostics",
+  WORKSPACE_DIAGNOSTIC_REFRESH: "workspace/diagnostic/refresh",
+});
+
+export const LSP_COMMAND = Object.freeze({
+  GO_TO_SOURCE_DEFINITION: "_typescript.goToSourceDefinition",
+});
+
+export const TYPESCRIPT_SERVER_COMMAND = Object.freeze({
+  DEFINITION_AND_BOUND_SPAN: "definitionAndBoundSpan",
+});
+
 export const LIMIT_MODE = Object.freeze({
   UNLIMITED: "unlimited",
   MAXIMUM: "maximum",
@@ -170,6 +247,24 @@ 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 SEMANTIC_EVIDENCE_STATUS = Object.freeze({
+  USABLE: "usable-as-requested",
+  FOLLOW_UP_REQUIRED: "follow-up-required",
+});
+
+export const SEMANTIC_EVIDENCE_FOLLOW_UP_REASON = Object.freeze({
+  COLLECTION_LIMITED: "collection-is-limited",
+  COLLECTION_PARTIAL: "collection-is-partial",
+  NO_DEFINITION_SELECTED: DEFINITION_SELECTION_STATUS.NONE,
+  MULTIPLE_DEFINITIONS_SELECTED: DEFINITION_SELECTION_STATUS.MULTIPLE,
+});
+
 export const SIGNATURE_SOURCE = Object.freeze({
   QUERY_POSITION_HOVER: "query-position-hover",
   RESOLVED_DEFINITION_HOVER: "resolved-definition-hover",
@@ -178,6 +273,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 +294,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 +328,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",
@@ -288,6 +390,7 @@ export const CI_REASON = Object.freeze({
   VERIFIED_DIAGNOSTIC_ERRORS: "verified-current-document-has-error-diagnostics",
   INCOMPLETE_EVIDENCE: "collection-is-limited-or-partial",
   UNTRUSTED_DIAGNOSTICS: "diagnostics-for-current-document-are-untrusted",
+  SEMANTIC_FOLLOW_UP_REQUIRED: "semantic-evidence-requires-follow-up",
   TOOL_EXECUTION_FAILED: "tool-execution-failed",
   INVALID_INPUT: "input-is-not-a-semantic-js-mcp-result",
 });
@@ -302,10 +405,10 @@ export const INTERNAL_RESOLUTION_SOURCE = Object.freeze({
 
 export const RESULT_SCHEMA = Object.freeze({
   NAME: PRODUCT.NAME,
-  VERSION: 5,
+  VERSION: 7,
 });
 
-export const SERVER_VERSION = "0.8.1";
+export const SERVER_VERSION = "0.10.0";
 
 export const REQUIRED_RUNTIME_COMPONENT = Object.freeze({
   TYPESCRIPT_LANGUAGE_SERVER: "typescript-language-server/lib/cli.mjs",
@@ -330,6 +433,12 @@ export const NODE_EVENT = Object.freeze({
   CLOSE: "close",
 });
 
+export const OPERATING_SYSTEM = Object.freeze({
+  LINUX: "linux",
+  MACOS: "darwin",
+  WINDOWS: "win32",
+});
+
 export const DEFAULT = Object.freeze({
   REQUEST_TIMEOUT_MS: 30_000,
   DIAGNOSTIC_WAIT_MS: 2_000,

package/scripts/agent-evaluation-contract.mjs

@@ -0,0 +1,165 @@
+import {
+  ACCOUNTING_STATUS,
+  CI_EXIT_CODE,
+  CI_STATUS,
+  COLLECTION_STATUS,
+  DEFINITION_SELECTION_STATUS,
+  SEMANTIC_EVIDENCE_FOLLOW_UP_REASON,
+  SEMANTIC_EVIDENCE_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,
+        semanticEvidence: Object.freeze({status: SEMANTIC_EVIDENCE_STATUS.USABLE, followUpReasons: Object.freeze([])}),
+        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,
+        definitionSelectionStatus: DEFINITION_SELECTION_STATUS.ONE,
+        semanticEvidence: Object.freeze({
+          status: SEMANTIC_EVIDENCE_STATUS.FOLLOW_UP_REQUIRED,
+          followUpReasons: Object.freeze([SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.COLLECTION_PARTIAL]),
+        }),
+        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,
+        semanticEvidence: Object.freeze({
+          status: SEMANTIC_EVIDENCE_STATUS.FOLLOW_UP_REQUIRED,
+          followUpReasons: Object.freeze([SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.MULTIPLE_DEFINITIONS_SELECTED]),
+        }),
+        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,
+        semanticEvidence: Object.freeze({
+          status: SEMANTIC_EVIDENCE_STATUS.FOLLOW_UP_REQUIRED,
+          followUpReasons: Object.freeze([SEMANTIC_EVIDENCE_FOLLOW_UP_REASON.NO_DEFINITION_SELECTED]),
+        }),
+        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`);