Improve prompt error handling and relative path support

client/integration-tests/primitives/prompts/explain_codeql_query/invalid_query_path/README.md

@@ -0,0 +1,22 @@
+# Integration Test: explain_codeql_query / invalid_query_path
+
+## Purpose
+
+Verify that the `explain_codeql_query` prompt returns a helpful error message
+when the user provides a `queryPath` that does not exist on disk.
+
+## Expected Behavior
+
+- The prompt handler resolves the relative path against the workspace root.
+- When the resolved path does not exist, the prompt returns a warning in the
+  response messages rather than throwing a raw MCP protocol error.
+- The warning message should mention the file was not found so the user can
+  correct the path.
+
+## Parameters
+
+| Parameter      | Value                          | Notes              |
+| -------------- | ------------------------------ | ------------------ |
+| `databasePath` | `nonexistent/path/to/database` | Does **not** exist |
+| `queryPath`    | `nonexistent/path/to/query.ql` | Does **not** exist |
+| `language`     | `javascript`                   | Valid language     |

client/integration-tests/primitives/prompts/explain_codeql_query/invalid_query_path/after/monitoring-state.json

@@ -0,0 +1,9 @@
+{
+  "sessions": [
+    {
+      "expectedContentPatterns": [
+        "does not exist"
+      ]
+    }
+  ]
+}

client/integration-tests/primitives/prompts/explain_codeql_query/invalid_query_path/before/monitoring-state.json

@@ -0,0 +1,8 @@
+{
+  "sessions": [],
+  "parameters": {
+    "databasePath": "nonexistent/path/to/database",
+    "queryPath": "nonexistent/path/to/query.ql",
+    "language": "javascript"
+  }
+}

client/src/lib/integration-test-runner.js

@@ -227,9 +227,34 @@ export class IntegrationTestRunner {
       this.logger.log(`Completed ${totalIntegrationTests} tool-specific integration tests`);
 
       // Also run workflow integration tests
-      await this.runWorkflowIntegrationTests(baseDir);
+      const workflowIntegrationSucceeded = await this.runWorkflowIntegrationTests(baseDir);
+      if (!workflowIntegrationSucceeded) {
+        this.logger.logTest(
+          "Workflow integration tests",
+          false,
+          new Error("Workflow integration tests did not complete successfully")
+        );
+      }
+
+      // Also run prompt integration tests
+      const promptIntegrationSucceeded = await this.runPromptIntegrationTests(baseDir);
+      if (!promptIntegrationSucceeded) {
+        this.logger.logTest(
+          "Prompt integration tests",
+          false,
+          new Error("Prompt integration tests did not complete successfully")
+        );
+      }
+
+      if (totalIntegrationTests === 0) {
+        this.logger.log(
+          "No integration tests were executed across tool, workflow, or prompt suites.",
+          "ERROR"
+        );
+        return false;
+      }
 
-      return totalIntegrationTests > 0;
+      return workflowIntegrationSucceeded && promptIntegrationSucceeded;
     } catch (error) {
       this.logger.log(`Error running integration tests: ${error.message}`, "ERROR");
       return false;
@@ -1095,6 +1120,155 @@ export class IntegrationTestRunner {
     return params;
   }
 
+  /**
+   * Run prompt-level integration tests.
+   * Discovers test fixtures under `integration-tests/primitives/prompts/`
+   * and calls `client.getPrompt()` for each, validating the response.
+   */
+  async runPromptIntegrationTests(baseDir) {
+    try {
+      this.logger.log("Discovering and running prompt integration tests...");
+
+      const promptTestsDir = path.join(baseDir, "..", "integration-tests", "primitives", "prompts");
+
+      if (!fs.existsSync(promptTestsDir)) {
+        this.logger.log("No prompt integration tests directory found", "INFO");
+        return true;
+      }
+
+      // Get list of available prompts from the server
+      const response = await this.client.listPrompts();
+      const prompts = response.prompts || [];
+      const promptNames = prompts.map((p) => p.name);
+
+      this.logger.log(`Found ${promptNames.length} prompts available on server`);
+
+      // Discover prompt test directories (each subdirectory = one prompt name)
+      const promptDirs = fs
+        .readdirSync(promptTestsDir, { withFileTypes: true })
+        .filter((dirent) => dirent.isDirectory())
+        .map((dirent) => dirent.name);
+
+      this.logger.log(
+        `Found ${promptDirs.length} prompt test directories: ${promptDirs.join(", ")}`
+      );
+
+      let totalPromptTests = 0;
+      let allPromptTestsPassed = true;
+      for (const promptName of promptDirs) {
+        if (!promptNames.includes(promptName)) {
+          this.logger.log(`Skipping ${promptName} - prompt not found on server`, "WARN");
+          continue;
+        }
+
+        const promptDir = path.join(promptTestsDir, promptName);
+        const testCases = fs
+          .readdirSync(promptDir, { withFileTypes: true })
+          .filter((dirent) => dirent.isDirectory())
+          .map((dirent) => dirent.name);
+
+        this.logger.log(`Running ${testCases.length} test case(s) for prompt ${promptName}`);
+
+        for (const testCase of testCases) {
+          const passed = await this.runSinglePromptIntegrationTest(promptName, testCase, promptDir);
+          totalPromptTests++;
+          if (!passed) {
+            allPromptTestsPassed = false;
+          }
+        }
+      }
+
+      this.logger.log(`Total prompt integration tests executed: ${totalPromptTests}`);
+      return totalPromptTests > 0 ? allPromptTestsPassed : true;
+    } catch (error) {
+      this.logger.log(`Error running prompt integration tests: ${error.message}`, "ERROR");
+      return false;
+    }
+  }
+
+  /**
+   * Run a single prompt integration test.
+   *
+   * Reads parameters from `before/monitoring-state.json`, calls `getPrompt()`,
+   * and validates that the response contains messages (no protocol-level error).
+   */
+  async runSinglePromptIntegrationTest(promptName, testCase, promptDir) {
+    const testName = `prompt:${promptName}/${testCase}`;
+    this.logger.log(`\nRunning prompt integration test: ${testName}`);
+
+    try {
+      const testCaseDir = path.join(promptDir, testCase);
+      const beforeDir = path.join(testCaseDir, "before");
+      const afterDir = path.join(testCaseDir, "after");
+
+      // Validate test structure
+      if (!fs.existsSync(beforeDir)) {
+        this.logger.logTest(testName, false, "Missing before directory");
+        return false;
+      }
+
+      if (!fs.existsSync(afterDir)) {
+        this.logger.logTest(testName, false, "Missing after directory");
+        return false;
+      }
+
+      // Load parameters from before/monitoring-state.json
+      const monitoringStatePath = path.join(beforeDir, "monitoring-state.json");
+      if (!fs.existsSync(monitoringStatePath)) {
+        this.logger.logTest(testName, false, "Missing before/monitoring-state.json");
+        return false;
+      }
+
+      const monitoringState = JSON.parse(fs.readFileSync(monitoringStatePath, "utf8"));
+      const params = monitoringState.parameters || {};
+      resolvePathPlaceholders(params, this.logger);
+
+      // Call the prompt
+      this.logger.log(`Calling prompt ${promptName} with params: ${JSON.stringify(params)}`);
+
+      const result = await this.client.getPrompt({
+        name: promptName,
+        arguments: params
+      });
+
+      // Validate that the response contains messages (no raw protocol error)
+      const hasMessages = result.messages && result.messages.length > 0;
+      if (!hasMessages) {
+        this.logger.logTest(testName, false, "Expected messages in prompt response");
+        return false;
+      }
+
+      // If the after/monitoring-state.json has expected content checks, validate
+      const afterMonitoringPath = path.join(afterDir, "monitoring-state.json");
+      if (fs.existsSync(afterMonitoringPath)) {
+        const afterState = JSON.parse(fs.readFileSync(afterMonitoringPath, "utf8"));
+
+        // Support both top-level expectedContentPatterns and sessions[].expectedContentPatterns
+        const sessions = afterState.sessions || [];
+        const topLevelPatterns = afterState.expectedContentPatterns || [];
+        const sessionPatterns =
+          sessions.length > 0 ? sessions[0].expectedContentPatterns || [] : [];
+        const expectedPatterns = topLevelPatterns.length > 0 ? topLevelPatterns : sessionPatterns;
+
+        if (expectedPatterns.length > 0) {
+          const text = result.messages[0]?.content?.text || "";
+          for (const pattern of expectedPatterns) {
+            if (!text.includes(pattern)) {
+              this.logger.logTest(testName, false, `Expected response to contain "${pattern}"`);
+              return false;
+            }
+          }
+        }
+      }
+
+      this.logger.logTest(testName, true, `Prompt returned ${result.messages.length} message(s)`);
+      return true;
+    } catch (error) {
+      this.logger.logTest(testName, false, `Error: ${error.message}`);
+      return false;
+    }
+  }
+
   /**
    * Run workflow-level integration tests
    * These tests validate complete workflows rather than individual tools

client/src/lib/mcp-test-suite.js

@@ -22,6 +22,7 @@ export class MCPTestSuite {
     await this.testReadResource();
     await this.testListPrompts();
     await this.testGetPrompt();
+    await this.testGetPromptWithInvalidPath();
   }
 
   /**
@@ -132,6 +133,59 @@ export class MCPTestSuite {
     }
   }
 
+  /**
+   * Test that prompts handle invalid file paths gracefully.
+   *
+   * The explain_codeql_query prompt requires a `queryPath` parameter.
+   * When given a nonexistent path it should return a user-friendly error
+   * message inside the prompt response rather than throwing a raw MCP
+   * protocol error.
+   */
+  async testGetPromptWithInvalidPath() {
+    try {
+      this.logger.log("Testing prompt error handling with invalid file path...");
+
+      const result = await this.client.getPrompt({
+        name: "explain_codeql_query",
+        arguments: {
+          databasePath: "nonexistent/path/to/database",
+          queryPath: "nonexistent/path/to/query.ql",
+          language: "javascript"
+        }
+      });
+
+      // The prompt should return messages (not throw) even for an invalid path
+      const hasMessages = result.messages && result.messages.length > 0;
+      if (!hasMessages) {
+        this.logger.logTest(
+          "Get Prompt with Invalid Path (explain_codeql_query)",
+          false,
+          "Expected messages in response"
+        );
+        return false;
+      }
+
+      // The response should contain a human-readable error about the invalid path
+      const text = result.messages[0]?.content?.text || "";
+      const mentionsPathError =
+        text.includes("does not exist") ||
+        text.includes("not found") ||
+        text.includes("could not be found") ||
+        text.includes("File not found") ||
+        text.includes("⚠");
+
+      this.logger.log(`Prompt response mentions path error: ${mentionsPathError}`);
+      this.logger.logTest("Get Prompt with Invalid Path (explain_codeql_query)", mentionsPathError);
+
+      return mentionsPathError;
+    } catch (error) {
+      // If the server throws instead of returning a message this test fails,
+      // which is the exact behaviour we want to fix.
+      this.logger.logTest("Get Prompt with Invalid Path (explain_codeql_query)", false, error);
+      return false;
+    }
+  }
+
   /**
    * Test listing prompts
    */

extensions/vscode/esbuild.config.js

@@ -37,6 +37,7 @@ const testSuiteConfig = {
     'test/suite/bridge.integration.test.ts',
     'test/suite/copydb-e2e.integration.test.ts',
     'test/suite/extension.integration.test.ts',
+    'test/suite/mcp-prompt-e2e.integration.test.ts',
     'test/suite/mcp-resource-e2e.integration.test.ts',
     'test/suite/mcp-server.integration.test.ts',
     'test/suite/mcp-tool-e2e.integration.test.ts',