@skyramp/mcp 0.3.9-rc.1 → 0.4.0-rc.2

package/build/commands/commandLibrary.d.ts

@@ -8,5 +8,5 @@ export declare function getCommandIds(): OneClickCommandId[];
  */
 export declare function lookupCommand(id: string): OneClickCommandDef;
 export { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
-export { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
+export { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
 export { LOCAL_DEV_TEST_CHANGES_COMMAND } from "./localDevTestChangesCommand.js";

package/build/commands/commandLibrary.js

@@ -1,11 +1,11 @@
 import { isLocalDevEnabled, isOneClickEnabled } from "../utils/featureFlags.js";
 import { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
-import { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
+import { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
 import { LOCAL_DEV_TEST_CHANGES_COMMAND } from "./localDevTestChangesCommand.js";
 /** Base predefined one-click commands */
 const BASE_COMMAND_LIBRARY = {
     test_given_endpoint_comprehensively: TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND,
-    full_repo_scan_recommend_generate_and_execute_top_n_tests: FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND,
+    full_repo_scan_recommend_generate_and_execute_top_n_tests: FULLREPO_RECOMMEND_GENERATE_EXECUTE_TESTS_COMMAND,
 };
 /** All enabled predefined one-click commands */
 function getCommandLibrary() {
@@ -39,5 +39,5 @@ export function lookupCommand(id) {
 }
 // Re-export commands for consumers that import from commandLibrary
 export { TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND } from "./testThisEndpointCommand.js";
-export { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
+export { FULLREPO_RECOMMEND_GENERATE_EXECUTE_TESTS_COMMAND } from "./recommendTestsAndExecuteCommand.js";
 export { LOCAL_DEV_TEST_CHANGES_COMMAND } from "./localDevTestChangesCommand.js";

package/build/commands/recommendTestsAndExecuteCommand.d.ts

@@ -1,2 +1,2 @@
 import type { OneClickCommandDef } from "../types/OneClickCommands.js";
-export declare const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND: OneClickCommandDef;
+export declare const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TESTS_COMMAND: OneClickCommandDef;

package/build/commands/recommendTestsAndExecuteCommand.js

@@ -2,11 +2,15 @@
  * Predefined One-Click Command: Recommend tests and generate and execute top recommended tests
  *
  * Spec order:
- *   skyramp_analyze_changes (combined analyze + discover + recommend)
- *   → Generate tests for top N recommended types
+ *   skyramp_analyze_changes (combined analyze + discover + suggest)
+ *   → Register a test plan, then generate the tests it holds
  *   → Execute each via skyramp_execute_test
+ *
+ * Step 2 works from the REGISTERED PLAN, not a ranked list. Full-repo scope follows
+ * the same path a diff does: the agent decides the candidate list itself and no
+ * server-side tier order picks the tests.
  */
-const fullRepoRecommendGenerateExecuteTopNSteps = [
+const fullRepoRecommendGenerateExecuteSteps = [
     {
         stepIndex: 0,
         title: "Ensure workspace is initialized",
@@ -22,24 +26,36 @@ const fullRepoRecommendGenerateExecuteTopNSteps = [
     },
     {
         stepIndex: 1,
-        title: "Analyze changes and get recommendations",
-        description: "Call skyramp_analyze_changes with repositoryPath and analysisScope from user. This single tool scans endpoints, discovers existing tests, and returns ranked test recommendations inline. Capture the stateFile path and the ranked recommendations for step 2.",
+        title: "Analyze the repository and read the candidate suggestions",
+        description: "Call skyramp_analyze_changes with repositoryPath and analysisScope from user. This single tool scans endpoints, discovers existing tests, and returns candidate test suggestions inline. The suggestions are candidates, not a selection: nothing is ranked, approved or mandatory. Capture the stateFile path — step 2 needs it — and read the suggestions alongside the endpoint and existing-test data the response carries.",
         toolCall: {
             toolName: "skyramp_analyze_changes",
-            description: "Analyze repo and generate ranked recommendations inline; returns stateFile",
+            description: "Analyze repo and return candidate suggestions inline; returns stateFile",
             inputs: {
                 repositoryPath: { source: "user", paramKey: "repositoryPath" },
                 scope: { source: "literal", value: "full_repo" },
             },
-            outputs: ["stateFile", "recommendations"],
+            outputs: ["stateFile"],
         },
-        conditionalGuidance: "Always call skyramp_analyze_changes — do not skip this step or use a pre-existing stateFile. Capture stateFile and ranked recommendations for step 2.",
+        conditionalGuidance: "Always call skyramp_analyze_changes — do not skip this step or use a pre-existing stateFile. Capture the stateFile for steps 2 and 3.",
     },
     {
         stepIndex: 2,
-        title: "Generate tests for top N recommended types",
-        description: "From the ranked recommendations returned by skyramp_analyze_changes in step 1, take the top N recommended test types (high priority first, then medium; N = topN from user, default 3).\n\nIMPORTANT — UI or E2E in top N: If UI or E2E test types are among the top N, treat each recommendation independently. For each such recommendation, first search the repository for existing trace files suitable for the endpoint or path associated with that recommendation (look for .zip or .json Skyramp trace files in the repo that reference the recommended endpoint path or URL). If suitable traces are found, use them directly as inputs to skyramp_ui_test_generation (playwrightInput) or skyramp_e2e_test_generation (trace + playwrightInput) — skip trace collection. If no suitable traces exist in the repo for that recommendation, collect them: call skyramp_start_trace_collection (playwright: true, outputDir: absolute path from workspace.yml), have the user interact with the recommended endpoint/path in the browser, then call skyramp_stop_trace_collection (playwrightEnabled: true, same outputDir). Use the produced trace file and Playwright zip as inputs for generation for that specific recommendation.\n\nFor all other types in the top N, for each recommendation call the corresponding generation tool using an endpoint URL derived from that recommendation (api.baseUrl + endpoint path, or a full endpoint URL included in the recommendation). If a recommendation does not specify a concrete endpoint, follow the scope indicated in the recommendation (e.g. service-wide or repo-wide) and omit endpointURL or use only api.baseUrl as appropriate. In all cases also pass apiSchema, language, framework, and outputDir from workspace.yml. Capture each generated test file path for step 3.",
-        conditionalGuidance: "Tool mapping by type — smoke: skyramp_smoke_test_generation, contract: skyramp_contract_test_generation, integration: skyramp_integration_test_generation, fuzz: skyramp_fuzz_test_generation, load: skyramp_load_test_generation, e2e: skyramp_e2e_test_generation, ui: skyramp_ui_test_generation. Limit to top N types. For UI/E2E: for each recommendation, (1) search the repo for existing traces for the endpoint or path associated with that recommendation; (2) if found, use them directly; (3) if not found, run skyramp_start_trace_collection → user interaction with the recommended endpoint/path → skyramp_stop_trace_collection, then use the produced traces. Record each generated test file path for step 3.",
+        title: "Register a test plan, then generate the tests it holds",
+        description: "Decide which tests this repository is missing, then register that decision with skyramp_register_test_plan (stateFile from step 1). Nothing in step 1 selected anything for you: keep a suggestion, keep none, keep all, or draft your own. How many distinct tests to write is your own judgment call — this command sets no ceiling and nothing supplies you with one. Each candidate declares what it asserts and whether it should fail or pass against the app as it stands; a full-repo scan has no diff, so no candidate needs a changed-line anchor. The tool stores every registration and returns objections — objections to a named candidate with the fact behind each one. Fix the plan and register it again (there is no limit), or answer an objection by its id through answers.\n\nThen generate one test per plan candidate. The generation tools admit a scenario the registered plan covers, so register the plan BEFORE the first generation call.\n\nIMPORTANT — UI or E2E candidates: treat each one independently. For each, first search the repository for existing trace files suitable for that candidate's endpoint or path (look for .zip or .json Skyramp trace files in the repo that reference it). If suitable traces are found, use them directly as inputs to skyramp_ui_test_generation (playwrightInput) or skyramp_e2e_test_generation (trace + playwrightInput) — skip trace collection. If no suitable traces exist in the repo for that candidate, collect them: call skyramp_start_trace_collection (playwright: true, outputDir: absolute path from workspace.yml), have the user interact with that endpoint or page in the browser, then call skyramp_stop_trace_collection (playwrightEnabled: true, same outputDir). Use the produced trace file and Playwright zip as inputs for generation for that specific candidate.\n\nFor every other candidate, call the generation tool its testType names, using an endpoint URL derived from the candidate's own steps (api.baseUrl + the step path). Also pass apiSchema, language, framework, and outputDir from workspace.yml. Capture each generated test file path for step 3.",
+        toolCall: {
+            toolName: "skyramp_register_test_plan",
+            description: "Register the complete test plan for this run, then generate from it. Every registration is stored and none is refused; the objections it returns are answered or fixed, never blocking.",
+            inputs: {
+                stateFile: { source: "step", stepIndex: 1, outputKey: "stateFile" },
+                candidates: {
+                    source: "literal",
+                    value: "the tests you decided to write, each with scenarioName, description, category, testType, steps and declarations — see the tool schema for each field's rule",
+                },
+            },
+            outputs: ["objections"],
+        },
+        conditionalGuidance: "Register the plan first, then generate — a scenario the plan does not cover is rejected by the generation tools. Tool mapping by testType — contract: skyramp_contract_test_generation, integration: skyramp_batch_scenario_test_generation then skyramp_integration_test_generation, e2e: skyramp_e2e_test_generation, ui: skyramp_ui_test_generation. Only these four types: never smoke, never fuzz, never load. Generate exactly the candidates the registered plan holds — no more, and drop none of them silently; if the work shows you a test the plan lacks, register the plan again with it first. For UI/E2E candidates: (1) search the repo for existing traces for that candidate; (2) if found, use them directly; (3) if not found, run skyramp_start_trace_collection → user interaction → skyramp_stop_trace_collection, then use the produced traces. Record each generated test file path for step 3.",
     },
     {
         stepIndex: 3,
@@ -62,24 +78,24 @@ const fullRepoRecommendGenerateExecuteTopNSteps = [
         conditionalGuidance: "Skip if step 2 generated no tests. Iterate over each generated test file path returned directly from the tools invoked in step 2 and call skyramp_execute_test once per file. Token resolution: (1) user-provided token; (2) token from .skyramp/workspace.yml or repo config; (3) empty string '' — let skyramp_execute_test surface auth errors, then ask the user for a Bearer token to re-run.",
     },
 ];
-export const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND = {
+export const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TESTS_COMMAND = {
     id: "full_repo_scan_recommend_generate_and_execute_top_n_tests",
-    name: "Full Repo: Recommend, Generate and Run TopN Tests",
-    description: "Run skyramp_analyze_changes to scan the repo and get ranked recommendations, generate tests for the top N recommended types, then execute the generated tests.",
+    name: "Full Repo: Recommend, Generate and Run Tests",
+    description: "Run skyramp_analyze_changes to scan the repo, register a test plan for the tests it is missing, generate the tests that plan holds, then execute them.",
     intent: {
         contextIndicators: [
-            "Use when the user wants to scan the entire repository with no specific endpoint or PR diff in mind — to get ranked test recommendations across all endpoints, generate the top N recommended test types, and execute them",
+            "Use when the user wants to scan the entire repository with no specific endpoint or PR diff in mind — to find the tests it is missing across all endpoints, generate them, and execute them",
             "Scope is always the full repository — the user has not mentioned a specific endpoint URL, path, or name",
             "Use when the user asks to recommend, generate, and execute tests for the whole repo or says something like 'run the full repo test workflow'",
             "Do NOT use when the user specifies a particular endpoint — use test_given_endpoint_comprehensively instead",
             "Do NOT use when the user asks about a PR diff or branch-scoped analysis — use skyramp_analyze_changes directly instead",
             "Do NOT use for simple single-tool requests such as 'generate a smoke test' or 'recommend tests for this PR'",
         ],
-        purpose: "Full repo scan: get recommendations → Generate top N types → Execute generated tests (no specific endpoint, no PR diff). Cleanup is handled automatically.",
-        workflowSummary: "Full Repo Scan → Recommend → Generate top N → Execute each test (cleanup is automatic)",
+        purpose: "Full repo scan: read the candidate suggestions → register a plan → generate the tests it holds → execute them (no specific endpoint, no PR diff). Cleanup is handled automatically.",
+        workflowSummary: "Full Repo Scan → Register plan → Generate the plan's tests → Execute each test (cleanup is automatic)",
         examples: {
             use: [
-                "scan the full repo and recommend and execute top 3 tests",
+                "scan the full repo and recommend and execute the tests it needs",
                 "run the full repo test workflow",
                 "recommend generate and execute tests for the whole repo",
                 "find the best tests to write for this codebase and run them",
@@ -91,11 +107,10 @@ export const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND = {
             ],
         },
     },
-    steps: fullRepoRecommendGenerateExecuteTopNSteps,
+    steps: fullRepoRecommendGenerateExecuteSteps,
     inputParams: {
         required: ["repositoryPath"],
         optional: [
-            "topN",
             "token",
             "endpointURL",
             "apiSchema",

package/build/commands/testThisEndpointCommand.js

@@ -2,11 +2,15 @@
  * Predefined One-Click Command: Test this endpoint
  *
  * Spec order:
- *   skyramp_analyze_changes (combined analyze + discover + recommend)
- *   → Evaluate missing (recommended minus existing)
- *   → Generate missing tests (by type)
+ *   skyramp_analyze_changes (combined analyze + discover + suggest)
+ *   → Register a test plan for the target endpoint
+ *   → Generate the tests the plan holds (by type)
  *   → Execute generated tests
  *   → [if existing tests found] Analyze test health → Optional batch execute → Actions
+ * Step 2 works from the REGISTERED PLAN, not a ranked list and not a server-side
+ * coverage pre-filter; the coverage question survives as a plan-time objection.
+ * KNOWN DEFECT, its own ticket: step 1 passes `scope: "full_repo"` so the scan
+ * finds a named endpoint — a scope flag doing endpoint discovery.
  */
 const comprehensivelyTestGivenEndpointSteps = [
     {
@@ -24,30 +28,42 @@ const comprehensivelyTestGivenEndpointSteps = [
     },
     {
         stepIndex: 1,
-        title: "Analyze changes and get recommendations",
-        description: "Call skyramp_analyze_changes with repositoryPath and scope from the one-click invocation. It scans endpoints, discovers existing tests, and returns ranked test recommendations along with a stateFile path. The response includes a JSON block with stateFile, sessionId, and a summary (including existingTestCount), plus a ranked recommendations section. Capture the stateFile path and the ranked recommendations for later steps. The full list of existing tests is not in the response — it is stored in the stateFile on disk.",
+        title: "Analyze the repository and read the candidate suggestions",
+        description: "Call skyramp_analyze_changes with repositoryPath and scope from the one-click invocation. It scans endpoints, discovers existing tests, and returns candidate test suggestions along with a stateFile path. The suggestions are candidates, not a selection: nothing is ranked, approved or mandatory. The response includes a JSON block with stateFile, sessionId, and a summary (including existingTestCount), plus the suggestions section. Capture the stateFile path — step 2 needs it — and read the suggestions and the endpoint data for the target endpoint. The full list of existing tests is not in the response — it is stored in the stateFile on disk.",
         toolCall: {
             toolName: "skyramp_analyze_changes",
-            description: "Analyze repo, discover tests, and generate ranked recommendations; returns stateFile",
+            description: "Analyze repo, discover tests, and return candidate suggestions; returns stateFile",
             inputs: {
                 repositoryPath: { source: "user", paramKey: "repositoryPath" },
                 scope: { source: "literal", value: "full_repo" },
             },
-            outputs: ["stateFile", "recommendations"],
+            outputs: ["stateFile"],
         },
-        conditionalGuidance: "If endpointURL is provided by the user, note it for use in generation steps. Capture the stateFile path and ranked recommendations from the response. The existing test list is not returned directly — it is embedded in the stateFile and will be used by skyramp_analyze_test_health in step 5.",
+        conditionalGuidance: "If endpointURL is provided by the user, note it — step 2's plan is about that endpoint. Capture the stateFile path from the response. The existing test list is not returned directly — it is embedded in the stateFile and will be used by skyramp_analyze_test_health in step 5.",
     },
     {
         stepIndex: 2,
-        title: "Evaluate missing tests",
-        description: "Using the ranked recommendations from step 1, determine which test types are missing coverage for the target endpoint. The step 1 response includes an existingTestCount in its summary — if it is 0 for the target endpoint, all recommended types are missing. If existingTestCount > 0, the full existing test list is in the stateFile (it will be processed by skyramp_analyze_test_health in step 5); for now, conservatively treat all recommended types as candidates to generate unless the recommendations explicitly note coverage. Build the list of types to generate in step 3. If all recommended types are already covered, skip steps 3 and 4.",
-        conditionalGuidance: "For each recommended type (high priority first, then medium), check whether the recommendations indicate existing coverage for the target endpoint. If not indicated, add the type to the 'generate' list. If existingTestCount from step 1 is 0, all types are missing. If all recommended types have coverage, steps 3 and 4 can be skipped.",
+        title: "Register a test plan for the target endpoint",
+        description: "Decide which tests the target endpoint is missing, then register that decision with skyramp_register_test_plan (stateFile from step 1). Every candidate must be about the target endpoint — that is what this workflow is for; use other endpoints only as setup or cleanup steps. Cover it the way its own source warrants: the success path, the error and boundary paths its validation implies, its auth boundary, and a multi-step scenario where it takes part in a real flow. Nothing in step 1 selected anything for you, and nothing removed a candidate for being already covered.\n\nEach candidate declares what it asserts and whether it should fail or pass against the app as it stands; this run has no diff, so no candidate needs a changed-line anchor. The tool stores every registration and returns objections. One of them names an endpoint an existing repository test already covers — answer it saying how your test differs, or make that candidate an in-place UPDATE of the existing test and drop it from the plan when you register it again. There is no registration limit and no objection blocks you.\n\nIf the plan ends up empty because every test the endpoint warrants already exists, skip steps 3 and 4 and go to step 5.",
+        toolCall: {
+            toolName: "skyramp_register_test_plan",
+            description: "Register the complete test plan for the target endpoint. Every registration is stored and none is refused; the objections it returns are answered or fixed, never blocking.",
+            inputs: {
+                stateFile: { source: "step", stepIndex: 1, outputKey: "stateFile" },
+                candidates: {
+                    source: "literal",
+                    value: "the tests you decided to write for the target endpoint, each with scenarioName, description, category, testType, steps and declarations — see the tool schema for each field's rule",
+                },
+            },
+            outputs: ["objections"],
+        },
+        conditionalGuidance: "Register the plan before any generation call — a scenario the plan does not cover is rejected by the generation tools. Every candidate's subject step must be the target endpoint. Existing coverage is an objection on the registration, not a reason to plan nothing: answer it or convert that candidate to an UPDATE of the existing test. If the registered plan holds no candidates, skip steps 3 and 4 and go to step 5.",
     },
     {
         stepIndex: 3,
-        title: "Generate missing tests (by type)",
-        description: "IMPORTANT — UI or E2E in missing list: If UI or E2E test types are in the 'missing' list, first search the repository for existing trace files suitable for the target endpoint (look for .zip or .json Skyramp trace files in the repo that reference the endpoint path or URL). If suitable traces are found, use them directly as inputs to skyramp_ui_test_generation (playwrightInput) or skyramp_e2e_test_generation (trace + playwrightInput) — skip trace collection. If no suitable traces exist in the repo, collect them: call skyramp_start_trace_collection (playwright: true, outputDir: absolute path from workspace.yml), have the user interact with the target endpoint in the browser, then call skyramp_stop_trace_collection (playwrightEnabled: true, same outputDir). Use the produced trace file and Playwright zip as inputs for generation.\n\nFor all other types in the 'missing' list, call the corresponding generation tool using endpointURL from the one-click invocation (or api.baseUrl + endpoint path from recommendation), apiSchema, language, framework, and outputDir from workspace.yml. Capture each generated test file path.",
-        conditionalGuidance: "Tool mapping by type — smoke: skyramp_smoke_test_generation, contract: skyramp_contract_test_generation, integration: skyramp_integration_test_generation, fuzz: skyramp_fuzz_test_generation, load: skyramp_load_test_generation, e2e: skyramp_e2e_test_generation, ui: skyramp_ui_test_generation. Only generate types in the 'missing' list. For UI/E2E: (1) search repo for existing traces for the target endpoint; (2) if found, use them directly; (3) if not found, run skyramp_start_trace_collection → user interaction → skyramp_stop_trace_collection, then use produced traces. Record each generated test file path for step 4.",
+        title: "Generate the tests your plan holds (by type)",
+        description: "IMPORTANT — UI or E2E candidates in the plan: first search the repository for existing trace files suitable for the target endpoint (look for .zip or .json Skyramp trace files in the repo that reference the endpoint path or URL). If suitable traces are found, use them directly as inputs to skyramp_ui_test_generation (playwrightInput) or skyramp_e2e_test_generation (trace + playwrightInput) — skip trace collection. If no suitable traces exist in the repo, collect them: call skyramp_start_trace_collection (playwright: true, outputDir: absolute path from workspace.yml), have the user interact with the target endpoint in the browser, then call skyramp_stop_trace_collection (playwrightEnabled: true, same outputDir). Use the produced trace file and Playwright zip as inputs for generation.\n\nFor every other candidate in the plan, call the generation tool its testType names, using endpointURL from the one-click invocation (or api.baseUrl + the candidate's own step path), apiSchema, language, framework, and outputDir from workspace.yml. Capture each generated test file path.",
+        conditionalGuidance: "Tool mapping by testType — contract: skyramp_contract_test_generation, integration: skyramp_batch_scenario_test_generation then skyramp_integration_test_generation, e2e: skyramp_e2e_test_generation, ui: skyramp_ui_test_generation. Only these four types: never smoke, never fuzz, never load. Generate exactly the candidates the plan registered in step 2 holds — a scenario the plan does not cover is rejected; if the work shows you a test the plan lacks, register the plan again with it first. For UI/E2E: (1) search repo for existing traces for the target endpoint; (2) if found, use them directly; (3) if not found, run skyramp_start_trace_collection → user interaction → skyramp_stop_trace_collection, then use produced traces. Record each generated test file path for step 4.",
     },
     {
         stepIndex: 4,
@@ -119,17 +135,17 @@ const comprehensivelyTestGivenEndpointSteps = [
 export const TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND = {
     id: "test_given_endpoint_comprehensively",
     name: "Test this endpoint comprehensively",
-    description: "Comprehensively test a REST API endpoint: analyze changes + discover existing tests + get recommendations in one step, then evaluate missing tests, generate only missing tests, execute them — then (if existing tests were found) run the test health analysis toolset (health assessment → optional batch execute → actions). State files stay in system temp.",
+    description: "Comprehensively test a REST API endpoint: analyze changes + discover existing tests + read candidate suggestions in one step, then register a test plan for that endpoint, generate the tests the plan holds, execute them — then (if existing tests were found) run the test health analysis toolset (health assessment → optional batch execute → actions). State files stay in system temp.",
     intent: {
         contextIndicators: [
             "Use when the user names or references a specific REST API endpoint (by path such as /api/products, full URL, or name such as 'products endpoint') and wants a complete multi-step test pipeline for it",
-            "Covers the full endpoint testing lifecycle: discover existing tests → evaluate missing coverage → generate missing tests → execute → health analysis → maintenance actions",
+            "Covers the full endpoint testing lifecycle: discover existing tests → register a test plan for the endpoint → generate the tests it holds → execute → health analysis → maintenance actions",
             "Only use when the user explicitly signals a full or deep pipeline — words like 'comprehensively', 'thoroughly', 'deep test', 'full test pipeline', or 'all test types'. Do NOT trigger on bare phrases like 'test this endpoint' or 'test the products endpoint' alone — those are ambiguous and may only mean a single smoke test",
             "Do NOT use for broad repo-level requests where no specific endpoint is named — use skyramp_analyze_changes directly instead",
             "Do NOT use for simple single-tool requests such as 'generate a smoke test for this endpoint' — those go directly to the generation tool",
         ],
-        purpose: "Deep test a given endpoint: discover existing → evaluate missing → generate missing → execute → (if existing found) health analysis → maintenance actions. Cleanup is handled automatically.",
-        workflowSummary: "Analyze Changes → Evaluate missing → Generate missing → Execute generated → [if existing] Test Health → Batch execute → Actions (cleanup is automatic)",
+        purpose: "Deep test a given endpoint: discover existing → register a plan for the endpoint → generate the plan's tests → execute → (if existing found) health analysis → maintenance actions. Cleanup is handled automatically.",
+        workflowSummary: "Analyze Changes → Register plan → Generate the plan's tests → Execute generated → [if existing] Test Health → Batch execute → Actions (cleanup is automatic)",
         examples: {
             use: [
                 "comprehensively test the products endpoint",
@@ -148,6 +164,6 @@ export const TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND = {
     steps: comprehensivelyTestGivenEndpointSteps,
     inputParams: {
         required: ["repositoryPath"],
-        optional: ["endpointURL", "apiSchema", "topN", "token"],
+        optional: ["endpointURL", "apiSchema", "token"],
     },
 };

package/build/index.js

@@ -26,7 +26,7 @@ import { registerEnhanceAssertionsTool } from "./tools/code-refactor/enhanceAsse
 import { registerBatchScenarioTestTool } from "./tools/generate-tests/generateBatchScenarioRestTool.js";
 import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js";
 import { registerBatchMockTool } from "./tools/generate-tests/batchMockGenerationTool.js";
-import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, registerRegisterTestPlanTool, } from "./tools/test-management/index.js";
+import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, registerRegisterTestPlanTool, registerResolveScreenTool, } from "./tools/test-management/index.js";
 import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
 import { registerSutSetupResource } from "./resources/sutSetupResource.js";
 import { registerTestbotResource } from "./resources/testbotResource.js";
@@ -44,7 +44,7 @@ import { registerAnalysisResources } from "./resources/analysisResources.js";
 import { registerProgressResource } from "./resources/progressResource.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { registerInitTriggerOnMCPInitialized } from "./utils/initAgent.js";
-import { isTestbotEnabled, isLocalDevEnabled } from "./utils/featureFlags.js";
+import { isTestbotEnabled, isLocalDevEnabled, isSkillsLoaded, } from "./utils/featureFlags.js";
 import { findRoot, readTestIdAttribute } from "./utils/pom-scope/index.js";
 import { discoverTestIdAttribute } from "./utils/pom-scope/testIdDiscovery.js";
 import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
@@ -170,10 +170,15 @@ testGenerationTools.forEach((registerTool) => registerTool(server));
 // Register modularization and code quality tools
 const codeQualityTools = [
     registerModularizationTool,
-    registerFixErrorTool,
     registerCodeReuseTool,
     registerEnhanceAssertionsTool,
 ];
+// With the Skyramp plugin loaded the agent already has the
+// fix-test-import-errors skill; the tool would be a second copy of
+// the same text (SKYR-4296).
+if (!isSkillsLoaded()) {
+    codeQualityTools.push(registerFixErrorTool);
+}
 codeQualityTools.forEach((registerTool) => registerTool(server));
 // Register analysis resources (MCP Resources for enriched data access)
 registerAnalysisResources(server);
@@ -183,6 +188,7 @@ registerAnalyzeChangesTool(server);
 registerAnalyzeTestHealthTool(server);
 registerActionsTool(server);
 registerRegisterTestPlanTool(server);
+registerResolveScreenTool(server);
 // Register workspace management tools
 registerInitScanWorkspaceTool(server);
 registerInitializeWorkspaceTool(server);

package/build/playwright/blueprintDigest.d.ts

@@ -0,0 +1,15 @@
+import type { BlueprintCaptureDigest } from "../types/BlueprintDigest.js";
+/** Where the JSON body of a `browser_blueprint` payload starts and ends. ONE
+ *  reader for both users; a second copy would drift and deliver an unshrunk
+ *  payload rather than fail. The body STOPS at the next `### ` header, since the
+ *  fork appends sections after `### Result` and only that one holds JSON. */
+export declare function blueprintJsonSpan(text: string): {
+    start: number;
+    end: number;
+} | undefined;
+export declare const MAX_ELEMENTS = 2000;
+/** The digest of one payload, or undefined when nothing in it keys to a page.
+ *  `previousUrl` is the url of the capture before this one: a repeat capture
+ *  carries no url of its own, so without it every element an action revealed is
+ *  dropped. Never throws — an unparseable payload costs a digest, not the capture. */
+export declare function digestFromBlueprintText(payload: string, previousUrl?: string): BlueprintCaptureDigest | undefined;

package/build/playwright/blueprintDigest.js

@@ -0,0 +1,152 @@
+/** Where the JSON body of a `browser_blueprint` payload starts and ends. ONE
+ *  reader for both users; a second copy would drift and deliver an unshrunk
+ *  payload rather than fail. The body STOPS at the next `### ` header, since the
+ *  fork appends sections after `### Result` and only that one holds JSON. */
+export function blueprintJsonSpan(text) {
+    if (typeof text !== "string")
+        return undefined;
+    const start = text.indexOf("{");
+    if (start === -1)
+        return undefined;
+    const nextSection = text.slice(start).search(/\n### /);
+    return { start, end: nextSection === -1 ? text.length : start + nextSection };
+}
+/** A capture is bounded, but the payload is not this module's to trust. */
+const MAX_DEPTH = 12;
+export const MAX_ELEMENTS = 2000;
+function text(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+function rowText(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const rows = value.filter((entry) => typeof entry === "string");
+    return rows.length > 0 ? rows : undefined;
+}
+/** Fill a repeating element's `{param}` placeholders from one row. A literal
+ *  substitution of what the capture recorded, never a pattern match; an unfilled
+ *  placeholder is left as written so the template still grounds a citation. */
+function fillTemplate(template, parameters) {
+    if (!parameters || typeof parameters !== "object")
+        return template;
+    const values = parameters;
+    return template.replace(/\{([^{}]+)\}/g, (placeholder, name) => {
+        const value = values[name];
+        return typeof value === "string" || typeof value === "number" ? String(value) : placeholder;
+    });
+}
+function identity(element) {
+    // Serialised rather than joined on a separator: a row's context text is page
+    // content and can hold any character, so any separator could be in it.
+    return JSON.stringify([element.role, element.accessibleName, element.testId ?? "", element.stableId ?? "", element.contextText ?? []]);
+}
+/** Every element this record describes. A repeating one keeps BOTH its template
+ *  and each filled-in row, because the agent lifts a row's rendered name. */
+function elementsOf(record) {
+    const role = text(record.role);
+    if (!role)
+        return [];
+    const testId = text(record.testId);
+    const stableId = text(record.stableId);
+    const base = (accessibleName, contextText) => ({
+        role,
+        accessibleName,
+        ...(testId ? { testId } : {}),
+        ...(stableId ? { stableId } : {}),
+        ...(contextText ? { contextText } : {}),
+    });
+    const name = text(record.accessibleName);
+    if (name)
+        return [base(name, rowText(record.contextText))];
+    const template = text(record.accessibleNameTemplate);
+    // An identifier with no name still counts: `uiElementGrounded` grounds on
+    // `testId` or `stableId` ALONE, so dropping it hid a citable capture.
+    if (!template)
+        return testId || stableId ? [base("", rowText(record.contextText))] : [];
+    const found = [base(template)];
+    for (const item of Array.isArray(record.items) ? record.items : []) {
+        if (!item || typeof item !== "object")
+            continue;
+        const row = item;
+        found.push(base(fillTemplate(template, row.parameters), rowText(row.contextText)));
+    }
+    return found;
+}
+/** Every element anywhere in the capture. WALKED structurally rather than read at
+ *  known paths: the fork nests them in three places today and may add a fourth.
+ *  The cost is an element-shaped record from somewhere unexpected, which only
+ *  makes the pool larger and the check softer. */
+function collectElements(root) {
+    const found = [];
+    let truncated = false;
+    const seen = new Set();
+    const stack = [{ value: root, depth: 0 }];
+    while (stack.length > 0) {
+        if (found.length >= MAX_ELEMENTS) {
+            truncated = true;
+            break;
+        }
+        const { value, depth } = stack.pop();
+        if (!value || typeof value !== "object" || depth > MAX_DEPTH)
+            continue;
+        if (Array.isArray(value)) {
+            for (const entry of value)
+                stack.push({ value: entry, depth: depth + 1 });
+            continue;
+        }
+        const record = value;
+        for (const element of elementsOf(record)) {
+            // Per ELEMENT, not per record: one repeating element materialises a row per
+            // entry of an unbounded `items` array, so one record can blow the cap.
+            if (found.length >= MAX_ELEMENTS) {
+                truncated = true;
+                break;
+            }
+            const key = identity(element);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            found.push(element);
+        }
+        for (const child of Object.values(record)) {
+            if (child && typeof child === "object")
+                stack.push({ value: child, depth: depth + 1 });
+        }
+    }
+    return { elements: found, truncated };
+}
+function urlOf(parsed) {
+    const blueprint = parsed.blueprint;
+    const inner = blueprint && typeof blueprint === "object" ? blueprint : undefined;
+    return text(parsed.url) ?? (inner ? text(inner.url) : undefined);
+}
+function pageHashOf(parsed) {
+    const blueprint = parsed.blueprint;
+    const inner = blueprint && typeof blueprint === "object" ? blueprint : undefined;
+    return text(parsed.pageHash) ?? (inner ? text(inner.pageHash) : undefined);
+}
+/** The digest of one payload, or undefined when nothing in it keys to a page.
+ *  `previousUrl` is the url of the capture before this one: a repeat capture
+ *  carries no url of its own, so without it every element an action revealed is
+ *  dropped. Never throws — an unparseable payload costs a digest, not the capture. */
+export function digestFromBlueprintText(payload, previousUrl) {
+    const span = blueprintJsonSpan(payload);
+    if (!span)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(payload.slice(span.start, span.end).trimEnd());
+    }
+    catch {
+        return undefined;
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return undefined;
+    const record = parsed;
+    const url = urlOf(record) ?? text(previousUrl);
+    if (!url)
+        return undefined;
+    const pageHash = pageHashOf(record);
+    const { elements, truncated } = collectElements(record);
+    return { url, ...(pageHash ? { pageHash } : {}), elements, ...(truncated ? { elementsTruncated: true } : {}) };
+}

package/build/playwright/blueprintDigestStore.d.ts

@@ -0,0 +1,31 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import type { BlueprintCaptureDigest } from "../types/BlueprintDigest.js";
+/** A run that takes more captures than this has a browsing problem of its own;
+ *  the cap is here so a runaway loop cannot grow the process without bound. */
+export declare const MAX_STORED_CAPTURES = 200;
+/** Record one capture, or do nothing. NOTHING HERE MAY COST THE CAPTURE: the
+ *  payload the agent receives is untouched and every failure is swallowed with a
+ *  log line. Gated on `currentRunStateFile()`, not `resolveRunStatePath()`, because
+ *  this gates BEHAVIOUR and `RUNNER_TEMP` is set in this repository's own CI. */
+export declare function recordBlueprintCapture(result: CallToolResult | undefined): void;
+/**
+ * Record where a `browser_navigate` took the browser.
+ *
+ * The server forwards the navigation, so it knows the destination without asking
+ * the agent — which is the point: a tool that exists to correct an agent's idea of
+ * which page it is on cannot take that page from the agent. Swallows everything,
+ * like the capture recorder: nothing here may cost a navigation.
+ */
+export declare function recordBrowserNavigation(url: unknown): void;
+/** The page the browser is on, and how the server came to know it: a navigation it
+ *  forwarded (`currentUrl`) or the last capture that named a page (`blueprint`). */
+export declare function lastKnownBrowserUrl(): {
+    url: string;
+    source: "currentUrl" | "blueprint";
+} | undefined;
+/** This run's digests, and no other run's — the same key the capture stored
+ *  them under. A copy: a reader that spliced the array would delete the run's
+ *  evidence. */
+export declare function capturedBlueprintDigests(): BlueprintCaptureDigest[];
+/** For tests, and as a safety hook between runs. */
+export declare function clearBlueprintDigests(): void;