@skyramp/mcp 0.0.50 → 0.0.52

package/build/prompts/startTraceCollectionPrompts.js

@@ -2,7 +2,10 @@
 import { logger } from "../utils/logger.js";
 export function registerStartTraceCollectionPrompt(mcpServer) {
     logger.info("registering start trace collection prompt");
-    mcpServer.prompt("skyramp_trace_prompt", "Skyramp trace collection prompt", {}, () => ({
+    mcpServer.registerPrompt("skyramp_trace_prompt", {
+        description: "Skyramp trace collection prompt",
+        argsSchema: {},
+    }, () => ({
         messages: [
             {
                 role: "user",

package/build/prompts/testGenerationPrompt.js

@@ -2,7 +2,10 @@
 import { logger } from "../utils/logger.js";
 export function registerTestGenerationPrompt(mcpServer) {
     logger.info("test generation prompt");
-    mcpServer.prompt("skyramp_test_generation_prompt", "Skyramp test generation prompt", {}, () => ({
+    mcpServer.registerPrompt("skyramp_test_generation_prompt", {
+        description: "Skyramp test generation prompt",
+        argsSchema: {},
+    }, () => ({
         messages: [
             {
                 role: "user",

package/build/prompts/testHealthPrompt.js

@@ -9,7 +9,10 @@
  * 5. Call skyramp_actions (with stateFile) to perform test updates
  */
 export function registerTestHealthPrompt(server) {
-    server.prompt("skyramp_test_health_analysis", "Skyramp Test Health Analysis", {}, () => {
+    server.registerPrompt("skyramp_test_health_analysis", {
+        title: "Skyramp Test Health Analysis",
+        argsSchema: {},
+    }, () => {
         const messages = [
             {
                 role: "user",

package/build/services/DriftAnalysisService.js

@@ -219,39 +219,59 @@ export class EnhancedDriftAnalysisService {
         try {
             const content = fs.readFileSync(testFile, "utf-8");
             const dependencies = new Set();
-            // Python imports: from X import Y, import X
+            // Python imports: only relative imports (from . import X, from .module import Y)
             const pythonImports = content.match(/^(?:from|import)\s+([^\s]+)/gm) || [];
             pythonImports.forEach((imp) => {
                 const match = imp.match(/(?:from|import)\s+([^\s]+)/);
                 if (match) {
-                    const module = match[1].replace(/\./g, "/");
-                    dependencies.add(`${module}.py`);
+                    const module = match[1];
+                    // Only include relative imports (starting with .)
+                    if (module.startsWith(".")) {
+                        // Count leading dots to determine parent traversal level
+                        const leadingDotsMatch = module.match(/^\.+/);
+                        const leadingDots = leadingDotsMatch
+                            ? leadingDotsMatch[0].length
+                            : 0;
+                        // Remove leading dots and convert remaining dots to slashes
+                        const moduleWithoutLeadingDots = module.substring(leadingDots);
+                        const modulePath = moduleWithoutLeadingDots.replace(/\./g, "/");
+                        // Build the correct relative path
+                        // . (1 dot) = current package (no ../)
+                        // .. (2 dots) = parent package (../)
+                        // ... (3 dots) = grandparent package (../../)
+                        const parentTraversal = leadingDots > 1 ? "../".repeat(leadingDots - 1) : "";
+                        if (modulePath) {
+                            dependencies.add(`${parentTraversal}${modulePath}.py`);
+                        }
+                    }
                 }
             });
-            // JavaScript/TypeScript imports
+            // JavaScript/TypeScript imports (only relative paths)
             const jsImports = content.match(/^import\s+.*?from\s+['"]([^'"]+)['"]/gm) || [];
             jsImports.forEach((imp) => {
                 const match = imp.match(/from\s+['"]([^'"]+)['"]/);
                 if (match) {
                     let depPath = match[1];
+                    // Only include relative imports (starting with . or ..)
                     if (depPath.startsWith(".")) {
                         depPath = path.resolve(path.dirname(testFile), depPath);
                         depPath = path.relative(this.repositoryPath, depPath);
+                        dependencies.add(depPath);
                     }
-                    dependencies.add(depPath);
                 }
             });
-            // Require statements
+            // Require statements (only relative paths)
             const requireImports = content.match(/require\(['"]([^'"]+)['"]\)/g) || [];
             requireImports.forEach((req) => {
                 const match = req.match(/require\(['"]([^'"]+)['"]\)/);
                 if (match) {
                     let depPath = match[1];
+                    // Only include relative requires (starting with . or ..)
                     if (depPath.startsWith(".")) {
                         depPath = path.resolve(path.dirname(testFile), depPath);
                         depPath = path.relative(this.repositoryPath, depPath);
+                        dependencies.add(depPath);
                     }
-                    dependencies.add(depPath);
                 }
             });
             return Array.from(dependencies);
@@ -483,7 +503,7 @@ export class EnhancedDriftAnalysisService {
             }
             const changeInfo = fileChanges.find((c) => c.file === file);
             if (changeInfo &&
-                (changeInfo.linesAdded > 5 || changeInfo.linesRemoved > 5)) {
+                (changeInfo.linesAdded > 3 || changeInfo.linesRemoved > 3)) {
                 if (/\.css|\.scss|\.less|styled|style/.test(file)) {
                     hasStylingChanges = true;
                 }
@@ -520,6 +540,7 @@ export class EnhancedDriftAnalysisService {
             /service/i,
             /model/i,
             /schema/i,
+            /router/i,
             /\.(yaml|yml|json)$/i,
         ];
         const uiPatterns = [
@@ -863,7 +884,7 @@ export class EnhancedDriftAnalysisService {
         return recommendations;
     }
     /**
-     * Analyze current state when no git history is available
+     * TODO: Analyze current state when no git history is available.
      */
     async analyzeCurrentState(testFile, repositoryPath, options) {
         logger.info(`Analyzing current state for test (no git history): ${testFile}`);
@@ -875,7 +896,7 @@ export class EnhancedDriftAnalysisService {
         const changes = [];
         const recommendations = [];
         let driftScore = 0;
-        // Check if dependencies exist
+        // Check if local dependent files exist
         const dependencies = await this.extractDependenciesWithTransitive(testFile, 2);
         const missingDependencies = [];
         for (const dep of dependencies) {

package/build/services/TestExecutionService.js

@@ -6,7 +6,7 @@ import { stripVTControlCharacters } from "util";
 import { logger } from "../utils/logger.js";
 const DEFAULT_TIMEOUT = 300000; // 5 minutes
 const MAX_CONCURRENT_EXECUTIONS = 5;
-const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.2";
+const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.5";
 const DOCKER_PLATFORM = "linux/amd64";
 const EXECUTION_PROGRESS_INTERVAL = 10000; // 10 seconds between progress updates during execution
 // Files and directories to exclude when mounting workspace to Docker container
@@ -345,11 +345,49 @@ export class TestExecutionService {
                 logger.error(`  Referenced in test as: ${sessionFile}`);
             }
         }
+        // Handle playwright save storage path
+        let saveStorageTargetPath = "";
+        if (options.playwrightSaveStoragePath) {
+            let saveStorageSource;
+            let saveStorageTarget;
+            if (path.isAbsolute(options.playwrightSaveStoragePath)) {
+                // Absolute path: use as-is
+                saveStorageSource = path.dirname(options.playwrightSaveStoragePath);
+                saveStorageTarget = path.dirname(options.playwrightSaveStoragePath);
+                saveStorageTargetPath = options.playwrightSaveStoragePath;
+            }
+            else {
+                // Relative path: resolve from workspace
+                const absolutePath = path.resolve(workspacePath, options.playwrightSaveStoragePath);
+                saveStorageSource = path.dirname(absolutePath);
+                saveStorageTarget = path.join(containerMountPath, path.dirname(options.playwrightSaveStoragePath));
+                saveStorageTargetPath = path.join(containerMountPath, options.playwrightSaveStoragePath);
+            }
+            // Ensure the directory exists on host
+            if (!fs.existsSync(saveStorageSource)) {
+                fs.mkdirSync(saveStorageSource, { recursive: true });
+            }
+            // Mount the directory as writable (not read-only)
+            if (!mountedPaths.has(saveStorageTarget)) {
+                logger.info(` docker run -v ${saveStorageSource}:${saveStorageTarget} ...`);
+                hostConfig.Mounts?.push({
+                    Type: "bind",
+                    Target: saveStorageTarget,
+                    Source: saveStorageSource,
+                    ReadOnly: false,
+                });
+                mountedPaths.add(saveStorageTarget);
+            }
+        }
         // Prepare environment variables
         const env = [
             `SKYRAMP_TEST_TOKEN=${options.token || ""}`,
             "SKYRAMP_IN_DOCKER=true",
         ];
+        // Add save storage path to environment if provided
+        if (saveStorageTargetPath) {
+            env.push(`PLAYWRIGHT_SAVE_STORAGE_PATH=${saveStorageTargetPath}`);
+        }
         if (process.env.SKYRAMP_DEBUG) {
             env.push(`SKYRAMP_DEBUG=${process.env.SKYRAMP_DEBUG}`);
         }

package/build/services/TestGenerationService.js

@@ -197,7 +197,7 @@ ${result}`;
             queryParams: params.queryParams,
             formParams: params.formParams,
             responseStatusCode: params.responseStatusCode,
-            traceFilePath: params.trace,
+            traceFilePath: params.trace ?? params.scenarioFile,
             generateInclude: params.include,
             generateExclude: params.exclude,
             generateInsecure: params.insecure,

package/build/tools/executeSkyrampTestTool.js

@@ -46,6 +46,10 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
             token: z
                 .string()
                 .describe("Skyramp authentication token for test execution. USE EMPTY STRING WHEN USER CONFIRMS 'No token required'"),
+            playwrightSaveStoragePath: z
+                .string()
+                .optional()
+                .describe("Path to save Playwright session storage after test execution for authentication purposes. Can be a relative path to the workspace (e.g., 'auth-session.json') or an absolute path. The session will be saved after the test completes."),
         },
         _meta: {
             keywords: ["run test", "execute test"],
@@ -83,6 +87,7 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
                 language: params.language,
                 testType: params.testType,
                 token: params.token,
+                playwrightSaveStoragePath: params.playwrightSaveStoragePath,
             }, onExecutionProgress);
             // Progress is already reported by TestExecutionService
             // Only report final status if not already at 100%

package/build/tools/generate-tests/generateE2ERestTool.js

@@ -33,7 +33,10 @@ export function registerE2ETestTool(server) {
 End-to-End tests validate complete user journeys by testing the entire application flow from frontend UI interactions to backend API responses. They ensure that all components work together correctly in realistic user scenarios, providing the highest confidence in application functionality.
 
 TRACE & UI INTEGRATION:
-E2E tests require both trace files (capturing backend API interactions) and Playwright recordings (capturing UI interactions captured using start_trace_collection tool) to generate comprehensive tests that validate the complete user experience.`,
+E2E tests require both trace files (capturing backend API interactions) and Playwright recordings (capturing UI interactions captured using start_trace_collection tool) to generate comprehensive tests that validate the complete user experience.
+
+**CRITICAL - When using trace parameter:**
+If \`trace\` parameter is provided (path to a trace file), DO NOT pass \`apiSchema\` or \`endpointURL\` parameters. The trace file already contains all necessary endpoint and schema information. Passing both will cause test generation to fail.`,
         inputSchema: e2eTestSchema,
         _meta: {
             keywords: ["e2e test", "end-to-end test"],

package/build/tools/generate-tests/generateIntegrationRestTool.js

@@ -30,7 +30,7 @@ export class IntegrationTestService extends TestGenerationService {
             ...super.buildBaseGenerationOptions(params),
             responseData: params.responseData,
             playwrightInput: params.playwrightInput,
-            trace: params.scenarioFile,
+            scenarioFile: params.scenarioFile,
         };
     }
     async handleApiAnalysis(params, generateOptions) {
@@ -44,7 +44,10 @@ export function registerIntegrationTestTool(server) {
 
 Integration tests validate that multiple services, components, or modules work together correctly. They test complex user workflows, service interactions, data flow between systems, and ensure that integrated components function as expected in realistic scenarios.
 
-**IMPORTANT: If an apiSchema parameter (OpenAPI/Swagger file path or URL) is provided, DO NOT attempt to read or analyze the file contents. These files can be very large. Simply pass the path/URL to the tool - the backend will handle reading and processing the schema file.**`,
+**IMPORTANT: If an apiSchema parameter (OpenAPI/Swagger file path or URL) is provided, DO NOT attempt to read or analyze the file contents. These files can be very large. Simply pass the path/URL to the tool - the backend will handle reading and processing the schema file.**
+
+**CRITICAL - When using scenarioFile or trace parameter:**
+If \`scenarioFile\` or \`trace\` parameter is provided, DO NOT pass \`apiSchema\` or \`endpointURL\` parameters. The scenario/trace file already contains all necessary endpoint and schema information. Passing both will cause test generation to fail.`,
         inputSchema: integrationTestSchema,
     }, async (params) => {
         const service = new IntegrationTestService();

package/build/tools/generate-tests/generateLoadRestTool.js

@@ -66,7 +66,10 @@ Load tests evaluate your application's performance, scalability, and stability u
   - loadNumThreads: "1" (1 thread)
   - Other load parameters should remain empty unless explicitly specified by the user
 
-**IMPORTANT: If an apiSchema parameter (OpenAPI/Swagger file path or URL) is provided, DO NOT attempt to read or analyze the file contents. These files can be very large. Simply pass the path/URL to the tool - the backend will handle reading and processing the schema file.**`,
+**IMPORTANT: If an apiSchema parameter (OpenAPI/Swagger file path or URL) is provided, DO NOT attempt to read or analyze the file contents. These files can be very large. Simply pass the path/URL to the tool - the backend will handle reading and processing the schema file.**
+
+**CRITICAL - When using trace parameter:**
+If \`trace\` parameter is provided (path to a trace file), DO NOT pass \`apiSchema\` or \`endpointURL\` parameters. The trace file already contains all necessary endpoint and schema information. Passing both will cause test generation to fail.`,
         inputSchema: loadTestSchema,
         _meta: {
             keywords: ["load test", "performance test"],

package/build/tools/generate-tests/generateScenarioRestTool.js

@@ -79,7 +79,14 @@ The AI should parse the natural language scenario and provide:
 
 **IMPORTANT: If an apiSchema parameter (OpenAPI/Swagger file path or URL) is provided, DO NOT attempt to read or analyze the file contents. These files can be very large. Simply pass the path/URL to the tool - the backend will handle reading and processing the schema file.**
 
-**Note:** This tool generates one request at a time. Call multiple times for multi-step scenarios.`,
+**Note:** This tool generates one request at a time. Call multiple times for multi-step scenarios.
+
+**CRITICAL - Integration Test Generation After Scenario Creation:**
+When generating an integration test using the scenario file created by this tool:
+1. Pass the scenario file path to the \`scenarioFile\` parameter
+2. DO NOT pass \`apiSchema\` or \`endpointURL\` parameters - the scenario file already contains all necessary endpoint and schema information
+3. Only provide: \`language\`, \`framework\`, \`outputDir\`, \`prompt\`, and \`scenarioFile\`
+Passing both scenarioFile and apiSchema/endpointURL will cause the test generation to fail.`,
         inputSchema: scenarioTestSchema,
     }, async (params) => {
         const service = new ScenarioGenerationService();

package/build/tools/test-maintenance/actionsTool.js

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { logger } from "../../utils/logger.js";
-import { AnalysisStateManager } from "../../utils/AnalysisStateManager.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import * as fs from "fs";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 const actionsSchema = {
@@ -39,8 +39,9 @@ Comprehensive report with executed actions, summary, and detailed analysis
         try {
             logger.info("Performing Actions");
             // Load data from state file
-            const stateManager = AnalysisStateManager.fromStatePath(args.stateFile);
-            const testAnalysisResults = await stateManager.readState();
+            const stateManager = StateManager.fromStatePath(args.stateFile);
+            const stateData = await stateManager.readData();
+            const testAnalysisResults = stateData?.tests || [];
             const fullState = await stateManager.readFullState();
             const repositoryPath = fullState?.metadata.repositoryPath || "";
             if (!testAnalysisResults || testAnalysisResults.length === 0) {
@@ -130,76 +131,86 @@ Comprehensive report with executed actions, summary, and detailed analysis
                     continue;
                 }
                 // Build update instructions
-                let instruction = `\n## 🔧 UPDATE REQUIRED: ${rec.testFile}\n\n`;
-                instruction += `**⚡ AUTOMATION DIRECTIVE:** You MUST immediately update this file. Do NOT ask for user confirmation. Use the 'write' tool to save changes directly.\n\n`;
-                instruction += `**Priority:** ${rec.priority}\n`;
-                instruction += `**Rationale:** ${rec.rationale}\n`;
-                instruction += `**Estimated Work:** ${rec.estimatedWork || "SMALL"}\n\n`;
+                let instruction = `\n### ${rec.testFile}\n\n`;
+                instruction += `**Priority:** ${rec.priority} | `;
+                instruction += `**Estimated Effort:** ${rec.estimatedWork || "Small"}\n\n`;
+                instruction += `**Why Update Needed:** ${rec.rationale}\n\n`;
                 if (driftData) {
-                    instruction += `**Drift Score:** ${driftData.driftScore ?? "N/A"}\n`;
-                    instruction += `**Changes Detected:** ${driftData.changes?.length || 0}\n`;
-                    instruction += `**Affected Files:** ${driftData.affectedFiles.files || 0}\n\n`;
+                    instruction += `**Analysis:**\n`;
+                    instruction += `- Drift Score: ${driftData.driftScore ?? "N/A"}\n`;
+                    instruction += `- Changes Detected: ${driftData.changes?.length || 0}\n`;
+                    instruction += `- Affected Files: ${driftData.affectedFiles.files || 0}\n\n`;
                 }
                 if (driftChanges.length > 0) {
-                    instruction += `**Specific Changes Detected:**\n`;
+                    instruction += `**Changes Detected:**\n`;
                     driftChanges.forEach((change) => {
-                        instruction += `- **${change.type}** (${change.severity}): ${change.description}\n`;
+                        instruction += `**${change.type}** (Severity: ${change.severity}): ${change.description}\n`;
                         if (change.details) {
-                            instruction += `  - Details: ${change.details}\n`;
+                            instruction += `   └─ ${change.details}\n`;
                         }
                         if (change.file) {
-                            instruction += `  - File: ${change.file}\n`;
+                            instruction += `   └─ In: \`${change.file}\`\n`;
                         }
                     });
                     instruction += `\n`;
                 }
                 if (issues.length > 0) {
-                    instruction += `**Issues to Address:**\n`;
+                    instruction += `**Issues Found:**\n`;
                     issues.forEach((issue) => {
-                        instruction += `- **${issue.type}** (${issue.severity}): ${issue.description}\n`;
+                        instruction += `**${issue.type}** (Severity: ${issue.severity}): ${issue.description}\n`;
                         if (issue.details) {
-                            instruction += `  - ${issue.details}\n`;
+                            instruction += `   └─ ${issue.details}\n`;
                         }
                     });
                     instruction += `\n`;
                 }
-                instruction += `**Current Test File Content:**\n\`\`\`\n${testFileContent}\n\`\`\`\n\n`;
-                instruction += `**🚀 REQUIRED ACTIONS (Execute Immediately):**\n`;
-                instruction += `1. Analyze the drift changes and issues listed above\n`;
-                instruction += `2. Update the test file to address ALL breaking changes and issues\n`;
-                instruction += `3. Ensure the test aligns with the current API schema and code changes\n`;
-                instruction += `4. **IMMEDIATELY use the 'write' tool to save the updated test file**\n`;
-                instruction += `5. Maintain the test's original structure and functionality while fixing compatibility issues\n`;
-                instruction += `6. **DO NOT wait for user approval - proceed with the update automatically**\n\n`;
+                instruction += `**Test File Content:**\n\`\`\`\n${testFileContent}\n\`\`\`\n\n`;
                 updateInstructions.push(instruction);
             }
             // Build final response
-            let responseText = `# ⚡ TEST UPDATE AUTOMATION TRIGGERED\n\n`;
-            responseText += `Found ${updateRecommendations.length} test(s) requiring UPDATE action.\n\n`;
-            responseText += `## 🚨 CRITICAL AUTOMATION DIRECTIVE\n\n`;
-            responseText += `**YOU MUST UPDATE ALL TEST FILES LISTED BELOW IMMEDIATELY**\n`;
-            responseText += `**DO NOT ASK FOR USER CONFIRMATION**\n`;
-            responseText += `**USE THE 'write' TOOL TO SAVE EACH FILE AFTER MAKING UPDATES**\n\n`;
-            responseText += `---\n`;
-            responseText += updateInstructions.join("\n---\n");
-            responseText += `\n\n## 📋 SUMMARY\n\n`;
-            responseText += `**Total tests to update:** ${updateRecommendations.length}\n`;
-            responseText += `**Test files:**\n`;
-            testFilesToUpdate.forEach((file) => {
-                responseText += `- ${file}\n`;
+            let responseText = `# 🔧 Test Update Recommendations\n\n`;
+            responseText += `Found **${updateRecommendations.length} test(s)** that need updates based on code changes.\n\n`;
+            responseText += `## 📋 Tests Requiring Updates\n\n`;
+            testFilesToUpdate.forEach((file, idx) => {
+                responseText += `${idx + 1}. \`${file}\`\n`;
             });
-            responseText += `\n**Required Actions:**\n`;
-            responseText += `1. Read each test file content (already provided above)\n`;
-            responseText += `2. Apply the necessary updates based on the drift changes\n`;
-            responseText += `3. Write the updated code back to the file using the 'write' tool\n`;
-            responseText += `4. Proceed to the next file\n`;
+            responseText += `\n---\n`;
+            responseText += updateInstructions.join("\n---\n");
+            responseText += `\n\n## ✅ Next Steps\n\n`;
+            responseText += `The AI assistant will:\n`;
+            responseText += `1. Review the changes and issues for each test\n`;
+            responseText += `2. Update test files to fix compatibility issues\n`;
+            responseText += `3. Preserve original test logic and structure\n`;
+            responseText += `4. Show you the changes made\n\n`;
             responseText += `5. At the end of the tool execution, MUST display the below message\n`;
             responseText += `**This tool is currently in Early Preview stage. Please verify the results.**\n\n`;
+            // Build LLM-only instructions (hidden from users)
+            const llmInstructions = `<!-- LLM_INSTRUCTIONS:
+{
+  "workflow": "test_maintenance",
+  "action": "execute_updates",
+  "auto_proceed": true,
+  "files_to_update": ${JSON.stringify(testFilesToUpdate)},
+  "update_count": ${updateRecommendations.length}
+}
+-->\n`;
             return {
                 content: [
                     {
                         type: "text",
                         text: responseText,
+                        // Explicitly mark as user-facing (though this is default)
+                        annotations: {
+                            audience: ["user"],
+                        },
+                    },
+                    {
+                        type: "text",
+                        text: llmInstructions,
+                        // Mark as assistant-only (may or may not be respected by Cursor)
+                        annotations: {
+                            audience: ["assistant"],
+                        },
                     },
                 ],
             };
@@ -220,7 +231,7 @@ Comprehensive report with executed actions, summary, and detailed analysis
             return errorResult;
         }
         finally {
-            const fullState = await AnalysisStateManager.fromStatePath(args.stateFile).readFullState();
+            const fullState = await StateManager.fromStatePath(args.stateFile).readFullState();
             const repositoryPath = fullState?.metadata.repositoryPath || "";
             AnalyticsService.pushMCPToolEvent(TOOL_NAME, errorResult, {
                 repositoryPath: repositoryPath,

package/build/tools/test-maintenance/analyzeTestDriftTool.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { EnhancedDriftAnalysisService } from "../../services/DriftAnalysisService.js";
 import { logger } from "../../utils/logger.js";
-import { AnalysisStateManager } from "../../utils/AnalysisStateManager.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 const TOOL_NAME = "skyramp_analyze_test_drift";
@@ -65,8 +65,9 @@ export function registerAnalyzeTestDriftTool(server) {
         let errorResult;
         try {
             // Load tests from state file
-            const stateManager = AnalysisStateManager.fromStatePath(args.stateFile);
-            const tests = await stateManager.readState();
+            const stateManager = StateManager.fromStatePath(args.stateFile);
+            const stateData = await stateManager.readData();
+            const tests = stateData?.tests || [];
             const fullState = await stateManager.readFullState();
             const repositoryPath = fullState?.metadata.repositoryPath || "";
             if (!tests || tests.length === 0) {
@@ -154,7 +155,7 @@ export function registerAnalyzeTestDriftTool(server) {
             logger.info(`Batch drift analysis completed. ${summary.totalTests} tests analyzed ` +
                 `(${summary.noGitHistory} without git history, ${summary.driftErrors} errors)`);
             // Save to state file
-            await stateManager.writeState(enrichedTests, {
+            await stateManager.writeData({ tests: enrichedTests }, {
                 repositoryPath: absoluteRepoPath,
                 step: "drift",
             });

package/build/tools/test-maintenance/calculateHealthScoresTool.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { TestHealthService } from "../../services/TestHealthService.js";
 import { logger } from "../../utils/logger.js";
-import { AnalysisStateManager } from "../../utils/AnalysisStateManager.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 const TOOL_NAME = "skyramp_calculate_health_scores";
 /**
@@ -54,8 +54,9 @@ Includes summary, recommendations, stateFile path, and automated workflow instru
         try {
             logger.info(`Calculating test health scores`);
             // Load tests from state file
-            const stateManager = AnalysisStateManager.fromStatePath(args.stateFile);
-            const testAnalysisResults = await stateManager.readState();
+            const stateManager = StateManager.fromStatePath(args.stateFile);
+            const stateData = await stateManager.readData();
+            const testAnalysisResults = stateData?.tests || [];
             const fullState = await stateManager.readFullState();
             const repositoryPath = fullState?.metadata.repositoryPath || "";
             if (!testAnalysisResults || testAnalysisResults.length === 0) {
@@ -163,7 +164,7 @@ Includes summary, recommendations, stateFile path, and automated workflow instru
                 return test;
             });
             // Store enriched test results with health data in state file
-            await stateManager.writeState(enrichedTestResults, {
+            await stateManager.writeData({ tests: enrichedTestResults }, {
                 repositoryPath: repositoryPath,
                 step: "health",
             });
@@ -196,36 +197,14 @@ Includes summary, recommendations, stateFile path, and automated workflow instru
                 responseText += `${idx + 1}. **${rec.testFile}** - Action: ${rec.action}, Priority: ${rec.priority}\n`;
                 responseText += `   - ${rec.rationale}\n`;
             });
-            responseText += `\n## State File\n`;
-            responseText += `**Path:** \`${stateManager.getStatePath()}\`\n`;
-            responseText += `**Size:** ${stateSize}\n\n`;
+            responseText += `\n## 💾 Analysis State\n`;
+            responseText += `Results saved to: \`${stateManager.getStatePath()}\` (${stateSize})\n\n`;
             responseText += `---\n\n`;
-            responseText += `# ⚠️ CRITICAL - NEXT ACTION REQUIRED ⚠️\n\n`;
-            responseText += `**YOU MUST IMMEDIATELY call the \`skyramp_actions\` tool with the following parameter:**\n\n`;
-            responseText += `\`\`\`json\n`;
-            responseText += `{\n`;
-            responseText += `  "stateFile": "${stateManager.getStatePath()}"\n`;
-            responseText += `}\n`;
-            responseText += `\`\`\`\n\n`;
-            responseText += `**DO NOT wait for user confirmation. Proceed directly to calling skyramp_actions.**\n\n`;
-            // Add structured data section for AI models to parse
-            responseText += `---\n\n`;
-            responseText += `## AUTOMATED WORKFLOW - NEXT STEP\n\n`;
-            responseText += `\`\`\`json\n`;
-            responseText += `{\n`;
-            responseText += `  "workflow": "test_maintenance",\n`;
-            responseText += `  "current_step": "health_calculation_complete",\n`;
-            responseText += `  "next_step": "execute_actions",\n`;
-            responseText += `  "required_action": {\n`;
-            responseText += `    "tool": "skyramp_actions",\n`;
-            responseText += `    "parameters": {\n`;
-            responseText += `      "stateFile": "${stateManager.getStatePath()}"\n`;
-            responseText += `    },\n`;
-            responseText += `    "auto_execute": true,\n`;
-            responseText += `    "wait_for_confirmation": false\n`;
-            responseText += `  }\n`;
-            responseText += `}\n`;
-            responseText += `\`\`\`\n`;
+            responseText += `## 🔄 Next Steps\n\n`;
+            responseText += `The analysis is complete. You can now:\n`;
+            responseText += `- Review the health scores above\n`;
+            responseText += `- Call \`skyramp_actions\` to see recommended fixes\n`;
+            responseText += `- Use the state file for further automation\n\n`;
             return {
                 content: [
                     {

package/build/tools/test-maintenance/discoverTestsTool.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { TestDiscoveryService } from "../../services/TestDiscoveryService.js";
 import { logger } from "../../utils/logger.js";
-import { AnalysisStateManager } from "../../utils/AnalysisStateManager.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import * as path from "path";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 const TOOL_NAME = "skyramp_discover_tests";
@@ -93,8 +93,8 @@ If you already know which tests to analyze, you can skip this and go directly to
                 // drift and execution will be added in subsequent steps
             }));
             // Save to state file
-            const stateManager = new AnalysisStateManager(args.sessionId);
-            await stateManager.writeState(testAnalysisResults, {
+            const stateManager = new StateManager("analysis", args.sessionId);
+            await stateManager.writeData({ tests: testAnalysisResults }, {
                 repositoryPath: absolutePath,
                 step: "discovery",
             });

package/build/tools/test-maintenance/executeBatchTestsTool.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { TestExecutionService } from "../../services/TestExecutionService.js";
 import { logger } from "../../utils/logger.js";
-import { AnalysisStateManager } from "../../utils/AnalysisStateManager.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
 import * as path from "path";
 import * as fs from "fs";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
@@ -55,8 +55,9 @@ export function registerExecuteBatchTestsTool(server) {
         try {
             logger.info(`Starting batch test execution`);
             // Load tests from state file
-            const stateManager = AnalysisStateManager.fromStatePath(args.stateFile);
-            const originalTestResults = await stateManager.readState();
+            const stateManager = StateManager.fromStatePath(args.stateFile);
+            const stateData = await stateManager.readData();
+            const originalTestResults = stateData?.tests || [];
             const fullState = await stateManager.readFullState();
             const repositoryPath = fullState?.metadata.repositoryPath || "";
             if (!originalTestResults || originalTestResults.length === 0) {
@@ -146,7 +147,7 @@ export function registerExecuteBatchTestsTool(server) {
                 return test;
             });
             // Save to state file
-            await stateManager.writeState(enrichedTests, {
+            await stateManager.writeData({ tests: enrichedTests }, {
                 repositoryPath: absoluteWorkspacePath,
                 step: "execution",
             });