@skyramp/mcp 0.0.65 → 0.1.0-rc.1

package/build/prompts/testbot/testbot-prompts.test.js

@@ -0,0 +1,142 @@
+jest.mock("@skyramp/skyramp", () => ({
+    WorkspaceConfigManager: jest.fn(),
+}));
+jest.mock("../../services/AnalyticsService.js", () => ({
+    AnalyticsService: { pushMCPToolEvent: jest.fn() },
+}));
+import { getTestbotPrompt } from "./testbot-prompts.js";
+// Minimal args to invoke getTestbotPrompt — only services matter for these tests
+const baseArgs = {
+    prTitle: "Test PR",
+    prDescription: "desc",
+    diffFile: ".skyramp_git_diff",
+    summaryOutputFile: "/tmp/summary.json",
+    repositoryPath: "/repo",
+};
+function callWithServices(services) {
+    return getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.diffFile, baseArgs.summaryOutputFile, baseArgs.repositoryPath, undefined, // baseBranch
+    undefined, // maxRecommendations
+    undefined, // maxGenerate
+    undefined, // maxCritical
+    undefined, // prNumber
+    undefined, // userPrompt
+    services);
+}
+function callWithStateOutputFile(stateOutputFile) {
+    return getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.diffFile, baseArgs.summaryOutputFile, baseArgs.repositoryPath, undefined, // baseBranch
+    undefined, // maxRecommendations
+    undefined, // maxGenerate
+    undefined, // maxCritical
+    undefined, // prNumber
+    undefined, // userPrompt
+    undefined, // services
+    stateOutputFile);
+}
+function callFollowUpWithStateOutputFile(stateOutputFile) {
+    return getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.diffFile, baseArgs.summaryOutputFile, baseArgs.repositoryPath, undefined, // baseBranch
+    undefined, // maxRecommendations
+    undefined, // maxGenerate
+    undefined, // maxCritical
+    undefined, // prNumber
+    "add more tests", // userPrompt — triggers follow-up path
+    undefined, // services
+    stateOutputFile);
+}
+describe("buildServiceContext (via getTestbotPrompt)", () => {
+    it("renders full service with all fields", () => {
+        const prompt = callWithServices([
+            {
+                serviceName: "backend",
+                language: "python",
+                framework: "pytest",
+                testDirectory: "tests/python",
+                api: { baseUrl: "http://localhost:8000" },
+            },
+        ]);
+        expect(prompt).toContain('<service name="backend">');
+        expect(prompt).toContain("<language>python</language>");
+        expect(prompt).toContain("<framework>pytest</framework>");
+        expect(prompt).toContain("<base_url>http://localhost:8000</base_url>");
+        expect(prompt).toContain("<output_dir>tests/python</output_dir>");
+        expect(prompt).toContain("</service>");
+        expect(prompt).toContain("<services>");
+        expect(prompt).toContain("</services>");
+    });
+    it("omits optional fields when absent", () => {
+        const prompt = callWithServices([{ serviceName: "minimal" }]);
+        expect(prompt).toContain('<service name="minimal">');
+        expect(prompt).not.toContain("<language>");
+        expect(prompt).not.toContain("<framework>");
+        expect(prompt).not.toContain("<base_url>");
+        expect(prompt).not.toContain("<output_dir>");
+    });
+    it("renders multiple services", () => {
+        const prompt = callWithServices([
+            { serviceName: "api", language: "python" },
+            { serviceName: "frontend", language: "typescript" },
+        ]);
+        expect(prompt).toContain('<service name="api">');
+        expect(prompt).toContain('<service name="frontend">');
+    });
+    it("does not render services block when services array is empty", () => {
+        const prompt = callWithServices([]);
+        expect(prompt).not.toContain("<services>");
+        expect(prompt).not.toContain("<service");
+    });
+    it("does not render services block when services is undefined", () => {
+        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.diffFile, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
+        expect(prompt).not.toContain("<services>");
+    });
+    it("escapes XML special characters in service name", () => {
+        const prompt = callWithServices([
+            { serviceName: 'my<service>&"name' },
+        ]);
+        expect(prompt).toContain('<service name="my&lt;service&gt;&amp;&quot;name">');
+        expect(prompt).not.toContain('my<service>&"name">');
+    });
+    it("escapes XML special characters in field values", () => {
+        const prompt = callWithServices([
+            {
+                serviceName: "svc",
+                testDirectory: "tests/a&b",
+                api: { baseUrl: "http://host?a=1&b=2" },
+            },
+        ]);
+        expect(prompt).toContain("<output_dir>tests/a&amp;b</output_dir>");
+        expect(prompt).toContain("<base_url>http://host?a=1&amp;b=2</base_url>");
+    });
+    it("places services block between REPOSITORY PATH and instruction line", () => {
+        const prompt = callWithServices([{ serviceName: "svc" }]);
+        const repoIdx = prompt.indexOf("<REPOSITORY PATH>");
+        const servicesIdx = prompt.indexOf("<services>");
+        const instructionIdx = prompt.indexOf("Use the Skyramp MCP server tools");
+        expect(repoIdx).toBeLessThan(servicesIdx);
+        expect(servicesIdx).toBeLessThan(instructionIdx);
+    });
+    it("has no extra blank line when services are absent", () => {
+        const prompt = getTestbotPrompt(baseArgs.prTitle, baseArgs.prDescription, baseArgs.diffFile, baseArgs.summaryOutputFile, baseArgs.repositoryPath);
+        // Should go directly from REPOSITORY PATH closing tag to "Use the Skyramp"
+        expect(prompt).toContain("</REPOSITORY PATH>\nUse the Skyramp MCP server tools");
+    });
+});
+describe("stateOutputFile in getTestbotPrompt", () => {
+    it("includes stateOutputFile in skyramp_analyze_changes call for first-run prompt", () => {
+        const stateFile = "/tmp/skyramp/analyze-changes-state.json";
+        const prompt = callWithStateOutputFile(stateFile);
+        // The prompt must pass stateOutputFile to skyramp_analyze_changes
+        expect(prompt).toContain(`\`stateOutputFile\`: "${stateFile}"`);
+    });
+    it("includes stateOutputFile in skyramp_analyze_changes call for follow-up prompt", () => {
+        const stateFile = "/tmp/skyramp/analyze-changes-state.json";
+        const prompt = callFollowUpWithStateOutputFile(stateFile);
+        expect(prompt).toContain(`\`stateOutputFile\`: "${stateFile}"`);
+    });
+    it("omits stateOutputFile from skyramp_analyze_changes call when not provided", () => {
+        const prompt = callWithStateOutputFile(undefined);
+        expect(prompt).not.toContain("stateOutputFile");
+    });
+    it("omits stateOutputFile from follow-up prompt when not provided", () => {
+        const prompt = callFollowUpWithStateOutputFile(undefined);
+        expect(prompt).not.toContain("stateOutputFile");
+    });
+});

package/build/services/ScenarioGenerationService.js

@@ -141,8 +141,8 @@ ${JSON.stringify(traceRequest, null, 2)}
                 if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
                     for (const [k, v] of Object.entries(parsed)) {
                         queryParams[k] = Array.isArray(v)
-                            ? v.map(String)
-                            : [String(v)];
+                            ? v.map((item) => typeof item === "object" && item !== null ? JSON.stringify(item) : String(item))
+                            : [typeof v === "object" && v !== null ? JSON.stringify(v) : String(v)];
                     }
                 }
                 else {

package/build/services/ScenarioGenerationService.test.js

@@ -196,6 +196,41 @@ describe("ScenarioGenerationService — auth header flavors", () => {
         expect(trace.RequestHeaders["Authorization"]).toBeUndefined();
     });
 });
+describe("ScenarioGenerationService — queryParams handling", () => {
+    it("serializes a flat primitive object correctly", () => {
+        const trace = generateTrace({ queryParams: '{"limit":"10","status":"active"}' });
+        expect(trace.QueryParams).toEqual({ limit: ["10"], status: ["active"] });
+    });
+    it("serializes numeric and boolean primitive values as strings", () => {
+        const trace = generateTrace({ queryParams: '{"page":2,"active":true}' });
+        expect(trace.QueryParams).toEqual({ page: ["2"], active: ["true"] });
+    });
+    it("JSON-stringifies nested object values instead of producing [object Object]", () => {
+        const trace = generateTrace({ queryParams: '{"filter":{"status":"active","min_price":10}}' });
+        expect(trace).not.toBeNull();
+        const filterVal = trace.QueryParams["filter"][0];
+        expect(filterVal).not.toBe("[object Object]");
+        expect(filterVal).toBe('{"status":"active","min_price":10}');
+    });
+    it("JSON-stringifies nested objects inside an array value", () => {
+        const trace = generateTrace({ queryParams: '{"ids":[{"id":1},{"id":2}]}' });
+        expect(trace).not.toBeNull();
+        expect(trace.QueryParams["ids"]).toEqual(['{"id":1}', '{"id":2}']);
+    });
+    it("passes through an array of primitive values unchanged", () => {
+        const trace = generateTrace({ queryParams: '{"tags":["a","b","c"]}' });
+        expect(trace.QueryParams["tags"]).toEqual(["a", "b", "c"]);
+    });
+    it("produces empty QueryParams when queryParams is omitted", () => {
+        const trace = generateTrace({});
+        expect(trace.QueryParams).toEqual({});
+    });
+    it("produces empty QueryParams and does not throw for invalid JSON", () => {
+        const trace = generateTrace({ queryParams: "not-valid-json" });
+        expect(trace).not.toBeNull();
+        expect(trace.QueryParams).toEqual({});
+    });
+});
 describe("ScenarioGenerationService — baseURL parsing", () => {
     it("parses http baseURL correctly", () => {
         const trace = generateTrace({

package/build/services/TestExecutionService.js

@@ -8,7 +8,7 @@ import { logger } from "../utils/logger.js";
 import { buildContainerEnv } from "./containerEnv.js";
 const DEFAULT_TIMEOUT = 300000; // 5 minutes
 const MAX_CONCURRENT_EXECUTIONS = 5;
-export const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.18";
+export const EXECUTOR_DOCKER_IMAGE = "skyramp/executor:v1.3.19";
 const DOCKER_PLATFORM = "linux/amd64";
 const EXECUTION_PROGRESS_INTERVAL = 10000; // 10 seconds between progress updates during execution
 // Temp file with valid empty JSON — used instead of /dev/null for .json config files

package/build/tools/code-refactor/modularizationTool.js

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import fs from "fs";
 import { logger } from "../../utils/logger.js";
-import { TestType } from "../../types/TestTypes.js";
+import { ProgrammingLanguage, TestType } from "../../types/TestTypes.js";
 import { ModularizationService, } from "../../services/ModularizationService.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { normalizeLanguageParams, resolveParamAliases, } from "../../utils/normalizeParams.js";
@@ -10,7 +10,7 @@ const modularizationSchema = {
         .string()
         .describe("The test file to process with modularization principles applied"),
     language: z
-        .string()
+        .nativeEnum(ProgrammingLanguage)
         .optional()
         .describe("The programming language of the test file. Inferred from file extension if not provided."),
     testType: z

package/build/tools/executeSkyrampTestTool.js

@@ -3,6 +3,7 @@ import { stripVTControlCharacters } from "util";
 import { TestExecutionService } from "../services/TestExecutionService.js";
 import { AnalyticsService } from "../services/AnalyticsService.js";
 import { getWorkspaceBaseUrl } from "../utils/workspaceAuth.js";
+import { ProgrammingLanguage, TestType } from "../types/TestTypes.js";
 const TOOL_NAME = "skyramp_execute_test";
 export function registerExecuteSkyrampTestTool(server) {
     server.registerTool(TOOL_NAME, {
@@ -36,11 +37,11 @@ For detailed documentation visit: https://www.skyramp.dev/docs/quickstart`,
                 .string()
                 .describe("The path to the workspace directory where the test file is located"),
             language: z
-                .string()
+                .nativeEnum(ProgrammingLanguage)
                 .describe("Programming language of the test file to execute (e.g., python, javascript, typescript, java)"),
             testType: z
-                .string()
-                .describe("Type of the test to execute (e.g., integration, contract, smoke, fuzz, load, e2e, ui). TEST TYPE MUST BE FROM [integration, contract, smoke, fuzz, load, e2e, ui]."),
+                .nativeEnum(TestType)
+                .describe("Type of the test to execute."),
             testFile: z
                 .string()
                 .describe("ALWAYS USE ABSOLUTE PATH to the test file to execute"),

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

@@ -2,25 +2,51 @@ import { z } from "zod";
 import path from "path";
 import { ScenarioGenerationService } from "../../services/ScenarioGenerationService.js";
 import fs from "fs";
-import { baseSchema, AUTH_PLACEHOLDER_TOKEN } from "../../types/TestTypes.js";
+import { baseSchema, AUTH_PLACEHOLDER_TOKEN, HttpMethod } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getWorkspaceAuthConfig, WorkspaceAuthType } from "../../utils/workspaceAuth.js";
 import { logger } from "../../utils/logger.js";
+import { getPersonaPrefix } from "../../prompts/architectPersona.js";
+function isJsonValue(v) {
+    if (v === undefined || v === null)
+        return true;
+    try {
+        JSON.parse(v);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isJsonObject(v) {
+    if (v === undefined || v === null)
+        return true;
+    try {
+        const p = JSON.parse(v);
+        return typeof p === "object" && !Array.isArray(p) && p !== null;
+    }
+    catch {
+        return false;
+    }
+}
 const stepSchema = z.object({
     method: z
-        .string()
-        .describe("HTTP method (GET, POST, PUT, DELETE, PATCH) for this step"),
+        .nativeEnum(HttpMethod)
+        .describe("HTTP method for this step."),
     path: z
         .string()
-        .describe("API path for this step. CRITICAL: For requests that reference an ID created by a prior step, use the ACTUAL ID value from the prior step's responseBody, NOT a template variable."),
+        .startsWith("/", { message: "path must begin with '/' (e.g. '/api/v1/products/123')" })
+        .describe("API path for this step, must start with '/'. CRITICAL: For requests that reference an ID created by a prior step, use the ACTUAL ID value from the prior step's responseBody, NOT a template variable."),
     requestBody: z
         .string()
         .optional()
-        .describe("JSON string of the request body for POST/PUT/PATCH requests"),
+        .refine(isJsonValue, { message: "requestBody must be valid JSON (e.g. '{\"name\":\"product\"}')." })
+        .describe("JSON string of the request body for POST/PUT/PATCH requests."),
     queryParams: z
         .string()
         .optional()
-        .describe("JSON string of URL query parameters for GET search/filter/list requests"),
+        .refine(isJsonObject, { message: "queryParams must be a JSON object string (e.g. '{\"limit\":\"10\"}')." })
+        .describe("JSON string of URL query parameters as a flat object for GET search/filter/list requests."),
     responseBody: z
         .string()
         .optional()
@@ -61,7 +87,7 @@ const batchScenarioSchema = {
     authHeader: z
         .string()
         .optional()
-        .describe("Which HTTP header carries the auth credential. Pass empty string or omit for unauthenticated endpoints."),
+        .describe("Which HTTP header carries the auth credential (e.g., 'Authorization', 'X-Api-Key'). Omit entirely to auto-resolve from workspace config. Pass empty string only for confirmed unauthenticated endpoints — empty string bypasses workspace auth resolution."),
     authScheme: z
         .string()
         .optional()
@@ -75,24 +101,27 @@ const batchScenarioSchema = {
 const TOOL_NAME = "skyramp_batch_scenario_test_generation";
 export function registerBatchScenarioTestTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `Generate a complete multi-step scenario file in a single call.
+        description: `${getPersonaPrefix()}Before calling this tool, you MUST output a <thinking> block that covers:
+1. Each step's method+path and confirmation it exists as a real endpoint (from OpenAPI spec, source code routes, or skyramp_analyze_changes output)
+2. Each step's requestBody or queryParams source — which schema field or prior step response provides these values
+3. The chaining strategy — which response fields from earlier steps are used as path params or body fields in later steps
+4. Auth resolution — authHeader/authScheme values and their source (workspace config / user input)
+If any step's endpoint cannot be confirmed without guessing, STOP and ask the user before calling the tool.
 
-This tool generates ALL TraceRequest objects for a multi-step scenario at once, producing
-the complete scenario JSON file in one invocation. Use this instead of calling
-\`skyramp_scenario_test_generation\` multiple times for multi-step integration tests.
+---
 
-**When to use:**
-- Multi-step integration test scenarios (e.g., create product → create order → update order → verify)
-- Any scenario requiring 2+ sequential API requests
+This tool generates the complete scenario JSON file for a multi-step integration test in a single call. Use this instead of calling skyramp_scenario_test_generation multiple times.
+
+**Mandatory spec mapping (do this before every call):**
+For each step in the \`steps\` array, confirm the method+path combination exists as a real endpoint (from OpenAPI spec, source code routes, or skyramp_analyze_changes output) before submitting. Do NOT invent paths. Do NOT use template variables — use CONCRETE ID values in paths (e.g. '/api/v1/products/70885', not '/api/v1/products/{id}').
 
-**What it does:**
-1. Accepts an ordered array of steps, each with method, path, requestBody, etc.
-2. Generates a TraceRequest for each step
-3. Writes the complete scenario JSON file with all steps
+**When to use:**
+- Any scenario requiring 2+ sequential API requests (create → update → verify, etc.)
+- Single-step scenarios where you need the output scenarioFile path for skyramp_integration_test_generation
 
-**After this tool:** Call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\` path.
+**After this tool succeeds:** immediately call \`skyramp_integration_test_generation\` with the \`scenarioFile\` path returned in this tool's output.
 
-**CRITICAL:** Use CONCRETE ID values in paths (e.g., '/api/v1/products/70885'), not template variables.`,
+**Error recovery:** If this tool returns an error for a specific step, the error message will tell you exactly which step failed (step N/total), the method+path, and the reason. Fix only the reported step and resubmit the full \`steps\` array — do NOT split into separate calls.`,
         inputSchema: batchScenarioSchema,
     }, async (params) => {
         if (params.authHeader === undefined) {

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

@@ -4,6 +4,7 @@ import { baseTestSchema, TestType } from "../../types/TestTypes.js";
 import { TestGenerationService, } from "../../services/TestGenerationService.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { ENHANCE_ASSERTIONS_FOR_INTEGRATION_AND_CONTRACTPROVIDER } from "../../prompts/test-maintenance/enhanceAssertionSection.js";
+import { getPersonaPrefix } from "../../prompts/architectPersona.js";
 const contractTestSchema = {
     ...baseTestSchema,
     pathParams: z
@@ -273,7 +274,21 @@ The generated consumer contract test contains a stub test function that uses Sky
 const TOOL_NAME = "skyramp_contract_test_generation";
 export function registerContractTestTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `Generate a contract test using Skyramp's deterministic test generation platform.
+        description: `${getPersonaPrefix()}Before calling this tool, you MUST output a <thinking> block that covers:
+1. The endpoint URL and HTTP method being tested
+2. Whether the endpoint is a nested resource (URL contains a path parameter like \`{id}\`, \`{flow_id}\`, etc.) — if YES, decide: do I have the request body to provision the parent, or should I use skipProvisionParents?
+3. Which assertions this test should validate (status code + key response schema fields with non-default values)
+4. Each required parameter and what value it will take, with source (workspace config / diff / schema / user input)
+NEVER use a hardcoded ID (UUID or integer) as a path parameter value. If a real resource ID is needed and cannot be provisioned, use skipProvisionParents instead.
+
+**Dynamic context (use this before generating):**
+If \`skyramp_analyze_changes\` has already run and returned a \`sessionId\`, fetch the endpoint detail before generating:
+\`skyramp://analysis/{sessionId}/endpoints/{path}/{method}\`
+This gives you the exact request body shape, response schema, and auth config for this endpoint. Use it to fill parameters and write accurate assertions — do not infer from source code when this resource is available.
+
+---
+
+Generate a contract test using Skyramp's deterministic test generation platform.
 
 Contract tests ensure your API implementation matches its OpenAPI/Swagger specification exactly. They validate request/response schemas, status codes, headers, and data types to prevent contract violations and API breaking changes.
 
@@ -281,6 +296,13 @@ Contract tests ensure your API implementation matches its OpenAPI/Swagger specif
 
 **IMPORTANT: If the endpoint URL contains path parameter placeholders (e.g., \`/products/{product_id}/reviews\`), pass the URL exactly as provided — do NOT substitute values for the placeholders. Leave \`pathParams\` empty unless the user has explicitly provided specific values.**
 
+**CRITICAL — Nested resource decision tree (follow this every time):**
+Does the endpoint URL contain a path parameter (e.g. \`/flows/{id}\`, \`/work_queues/{id}/stats\`)?
+- **YES, and \`apiSchema\` is provided** → use \`parentRequestData\` to supply the request body that creates the parent resource. The key must be the exact path parameter name (e.g. \`id\`, \`flow_id\`). The backend will provision the parent, extract the real ID, and inject it into the test.
+- **YES, but \`apiSchema\` is NOT available** → set \`skipProvisionParents: true\` (with \`providerMode: true\`). The test will verify the error-path contract (404) rather than the success path.
+- **NO path parameters** → no action needed; proceed normally.
+NEVER substitute a hardcoded UUID or integer for a path parameter. A hardcoded ID will always 404 in a clean environment and produces a useless test.
+
 **Modes:**
 - Default (no mode set): both \`providerMode\` and \`consumerMode\` default to false. This generates both provider and consumer contract tests — equivalent to setting both modes to true.
 - \`providerMode\`: set to true ONLY if the user explicitly requests a provider-side contract test. Optionally specify \`providerOutput\` for the output file path.
@@ -288,11 +310,11 @@ Contract tests ensure your API implementation matches its OpenAPI/Swagger specif
 - Both \`providerMode\` and \`consumerMode\` can be enabled simultaneously to generate both sides.
 
 **Chaining (requires \`apiSchema\`):**
-- \`parentRequestData\`: map of parent request data for chained test generation. Not allowed with \`consumerMode\` or \`skipProvisionParents\`.
-- \`parentStatusCode\`: map of parent response status codes for chained test generation. Not allowed with \`consumerMode\` or \`skipProvisionParents\`.
+- \`parentRequestData\`: map of parent request data for chained test generation. Key = exact path parameter name. Value = JSON string of the request body to create that parent resource. Not allowed with \`consumerMode\` or \`skipProvisionParents\`.
+- \`parentStatusCode\`: expected HTTP status code for each parent provisioning call (e.g. \`{"id": "201"}\`). Not allowed with \`consumerMode\` or \`skipProvisionParents\`.
 
 **Provider setup/teardown:**
-- \`skipProvisionParents\`: when true, skips generating setup/teardown functions for the provider contract test. Requires \`providerMode\`. Not allowed with \`parentRequestData\` or \`parentStatusCode\`.`,
+- \`skipProvisionParents\`: when true, skips generating setup/teardown functions for the provider contract test. Use this when \`apiSchema\` is unavailable and the endpoint requires a parent resource. Requires \`providerMode\`. Not allowed with \`parentRequestData\` or \`parentStatusCode\`.`,
         inputSchema: contractTestSchema,
     }, async (params) => {
         const service = new ContractTestService();

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

@@ -3,6 +3,7 @@ import { baseTestSchema, baseTraceSchema, TestType, codeRefactoringSchema, } fro
 import { TestGenerationService, } from "../../services/TestGenerationService.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { ENHANCE_ASSERTIONS_FOR_INTEGRATION_AND_CONTRACTPROVIDER } from "../../prompts/test-maintenance/enhanceAssertionSection.js";
+import { getPersonaPrefix } from "../../prompts/architectPersona.js";
 const integrationTestSchema = z
     .object({
     ...baseTestSchema,
@@ -15,19 +16,20 @@ const integrationTestSchema = z
     exclude: baseTraceSchema.shape.exclude.optional(),
     scenarioFile: z
         .string()
-        .describe("Path to the scenario file to be used for test generation. This file is generated by the skyramp_scenario_test_generation tool.")
-        .optional(),
+        .endsWith(".json", { message: "scenarioFile must be a path to a .json file." })
+        .optional()
+        .describe("Absolute path to the scenario JSON file produced by skyramp_batch_scenario_test_generation. " +
+        "When provided, DO NOT also pass apiSchema or endpointURL — the scenario file already contains all endpoint information."),
     ...codeRefactoringSchema.shape,
     ...baseTestSchema,
     output: baseTestSchema.output.describe("Name of the output test file. " +
-        "If the user does not specify a filename and a scenarioFile is provided, derive the output name from the scenario filename to avoid overwriting other tests. " +
-        "The backend default 'integration_test.py' is generic and will collide when multiple tests are generated. " +
-        "Derivation rule: take the scenario filename (no path, no extension), strip the leading 'scenario_' prefix, " +
-        "replace every hyphen and non-alphanumeric character with an underscore, then append '_integration_test' and the language extension. " +
+        "When scenarioFile is provided and user did not specify a name, derive it: " +
+        "strip the path and 'scenario_' prefix, replace hyphens/non-alphanum with underscores, append '_integration_test' + language extension. " +
         "Examples: " +
         "'scenario_orders-patch-add-items-recalculate.json' → 'orders_patch_add_items_recalculate_integration_test.py' (Python) or 'orders_patch_add_items_recalculate_integration_test.spec.ts' (Playwright). " +
         "'scenario_products-crud.json' → 'products_crud_integration_test.py'. " +
-        "Extensions: '.py' for pytest, '.spec.ts'/'.spec.js' for Playwright, '.java' for JUnit."),
+        "Extensions: '.py' for pytest, '.spec.ts'/'.spec.js' for Playwright, '.java' for JUnit. " +
+        "NEVER use the default 'integration_test.py' when scenarioFile is set — it collides with other generated tests."),
     endpointURL: baseTestSchema.endpointURL.default(""),
 })
     .omit({ method: true }).shape;
@@ -48,7 +50,7 @@ export class IntegrationTestService extends TestGenerationService {
     }
     buildAssertionEnhancementInstructions() {
         return `
-⏭️ **CRITICAL NEXT STEP — Enhance response body assertions after each request:**
+**CRITICAL NEXT STEP — Enhance response body assertions after each request:**
 
 The generated integration test contains only basic status-code assertions after each \`send_request\` / \`sendRequest\` call. For every request in the test (especially POST, PUT, and GET), add meaningful assertions on the response body using the rules below.
 
@@ -72,16 +74,45 @@ ${ENHANCE_ASSERTIONS_FOR_INTEGRATION_AND_CONTRACTPROVIDER}
 const TOOL_NAME = "skyramp_integration_test_generation";
 export function registerIntegrationTestTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `Generate an integration test using Skyramp's deterministic test generation platform.
+        description: `${getPersonaPrefix()}Before calling this tool, you MUST output a <thinking> block that covers:
+1. The endpoint URL(s) and HTTP method(s) involved in this multi-step workflow
+2. Why an integration test (multi-step workflow validation) is the right choice for this intent
+3. Which assertions this test should validate at each step (status code + key chained response fields)
+4. Each required parameter and what value it will take, with source (workspace config / diff / scenario file / user input)
+If any required parameter cannot be determined without guessing, STOP and ask the user before calling the tool.
+
+---
+
+Generate an integration test from a scenario file or a live endpoint trace.
+
+**Two mutually exclusive modes — choose exactly one:**
+1. **Scenario mode** (preferred for multi-step flows): pass \`scenarioFile\` (absolute path to the .json file returned by skyramp_batch_scenario_test_generation). Do NOT pass \`apiSchema\` or \`endpointURL\` in this mode. Passing both causes: "scenarioFile is mutually exclusive with apiSchema and endpointURL."
+2. **Direct mode**: pass \`endpointURL\` and optionally \`apiSchema\`. Do NOT pass \`scenarioFile\`.
 
-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.
+**Auth — scenario mode only:**
+- If workspace has \`api.authType\` set: omit ALL auth params — workspace config handles the Bearer prefix. Passing auth alongside workspace authType causes: "Auth header and auth type cannot be supported at the same time."
+- If workspace has no \`api.authType\`: pass \`authHeader\` only (no \`authScheme\`, no \`authToken\`).
 
-**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.**
+**Output filename:** When \`scenarioFile\` is provided and user did not specify a name, derive it: strip path and 'scenario_' prefix, replace hyphens/non-alphanum with underscores, append '_integration_test' + language extension. Example: 'scenario_orders-patch.json' → 'orders_patch_integration_test.py'. Never use the default 'integration_test.py' when scenarioFile is set — it collides.
 
-**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.`,
+**IMPORTANT:** If \`apiSchema\` is provided in direct mode, pass the path/URL as-is — do NOT read the file contents. The backend processes it.`,
         inputSchema: integrationTestSchema,
     }, async (params) => {
+        if (params.scenarioFile && (params.apiSchema || params.endpointURL)) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "**skyramp_integration_test_generation Error: Conflicting parameters**\n\n" +
+                            "`scenarioFile` is mutually exclusive with `apiSchema` and `endpointURL`.\n\n" +
+                            "**Received:** scenarioFile=" + params.scenarioFile +
+                            (params.apiSchema ? ", apiSchema=" + params.apiSchema : "") +
+                            (params.endpointURL ? ", endpointURL=" + params.endpointURL : "") + "\n\n" +
+                            "**How to fix:** Remove `apiSchema` and `endpointURL` when passing `scenarioFile` — " +
+                            "the scenario file already contains all endpoint and schema information.",
+                    }],
+                isError: true,
+            };
+        }
         const service = new IntegrationTestService();
         const result = await service.generateTest(params);
         AnalyticsService.pushTestGenerationToolEvent(TOOL_NAME, result, params).catch(() => {

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

@@ -4,6 +4,7 @@ import { baseSchema, AUTH_PLACEHOLDER_TOKEN } from "../../types/TestTypes.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { getWorkspaceAuthConfig, WorkspaceAuthType } from "../../utils/workspaceAuth.js";
 import { logger } from "../../utils/logger.js";
+import { getPersonaPrefix } from "../../prompts/architectPersona.js";
 const scenarioTestSchema = {
     scenarioName: z
         .string()
@@ -54,7 +55,7 @@ const scenarioTestSchema = {
         .string()
         .optional()
         .default("")
-        .describe("Which HTTP header carries the auth credential. Examples: 'Authorization' (Bearer/Token auth), 'X-Api-Key' (API key auth), 'Cookie' (session auth). Pass empty string to skip auth for unauthenticated endpoints."),
+        .describe("Which HTTP header carries the auth credential (e.g., 'Authorization', 'X-Api-Key', 'Cookie'). Omit or pass empty string to auto-resolve from workspace config. To force an unauthenticated request, omit AND ensure no workspace auth is configured."),
     authScheme: z
         .string()
         .optional()
@@ -78,50 +79,27 @@ const scenarioTestSchema = {
 const TOOL_NAME = "skyramp_scenario_test_generation";
 export function registerScenarioTestTool(server) {
     server.registerTool(TOOL_NAME, {
-        description: `Generate a single trace request from AI-parsed scenario parameters.
+        description: `${getPersonaPrefix()}Before calling this tool, you MUST output a <thinking> block that covers:
+1. The specific API endpoint (method + concrete path with real IDs, not templates)
+2. The request body fields and their values, with source (schema / prior step response / user input)
+3. The expected response status code and key response fields to chain into subsequent steps
+4. Whether this step depends on a prior step's response ID — if so, confirm the ID value is known
+If a required path parameter or request body field cannot be determined without guessing, STOP and ask the user before calling the tool.
 
-This tool generates a single TraceRequest object using parameters that have been parsed by AI from a natural language scenario. The AI should analyze the scenario and provide structured parameters instead of relying on hardcoded parsing logic.
+---
 
-**What it does:**
-1. **Accept AI-Parsed Data**: Takes structured parameters parsed by AI from natural language
-2. **Generate Trace Request**: Creates a single TraceRequest object with proper format
-3. **File Management**: Appends the request to an existing trace file or creates a new one
-4. **Dynamic Source**: IF DNS NAME IS PROVIDED, USE IT FOR SOURCE IP AND PORT
+**Dynamic context (use this before generating):**
+If \`skyramp_analyze_changes\` has already run and returned a \`sessionId\`, fetch the endpoint detail before building this step:
+\`skyramp://analysis/{sessionId}/endpoints/{path}/{method}\`
+This gives you the exact request body fields, types, and required vs optional distinction — use it to construct accurate request bodies instead of guessing from field names.
 
-**Output:**
-Returns a single TraceRequest object with:
-- Dynamic source IP and port
-- Destination host (extracted from API schema)
-- HTTP method and path (provided by AI)
-- Request and response bodies (provided by AI or generated)
-- Request and response headers
-- Status code and timestamp
-- Network details (port, scheme)
+---
 
-**AI Responsibilities:**
-The AI should parse the natural language scenario and provide:
-- HTTP method (POST, GET, PUT, DELETE)
-- API path with CONCRETE ID values, not templates (e.g., /api/v1/products/70885, NOT /api/v1/products/{product_id})
-- Request body (JSON string) for POST/PUT/PATCH requests
-- Query parameters (JSON string) for GET search/filter/list requests — NEVER put query params in requestBody
-- Response body (JSON string, if applicable)
-- Status code (optional, defaults based on method)
-- Entity details (name, price, quantity, ID as needed)
+Generate a single-step scenario trace request. For multi-step scenarios, prefer \`skyramp_batch_scenario_test_generation\` which generates all steps in one call.
 
-**Requirements:**
-- Natural language scenario description
-- API schema (OpenAPI/Swagger file or URL) for destination extraction
-- AI-parsed HTTP method and path (required)
-- AI-parsed request/response bodies (optional)
+**Path must use CONCRETE ID values** (e.g. '/api/v1/products/70885', not '/api/v1/products/{id}'). Use \`queryParams\` for GET filters/search — never \`requestBody\`.
 
-**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. Provide: \`language\`, \`framework\`, \`outputDir\`, \`prompt\`, and \`scenarioFile\`. Auth parameters are automatically extracted from the scenario trace; only pass \`authHeader\`/\`authScheme\` if you need to override the trace values.
-Passing both scenarioFile and apiSchema/endpointURL will cause the test generation to fail.`,
+**After this tool:** call \`skyramp_integration_test_generation\` with the returned \`scenarioFile\` path. Do NOT also pass \`apiSchema\` or \`endpointURL\` — the scenario file contains all endpoint information.`,
         inputSchema: scenarioTestSchema,
     }, async (params) => {
         if (!params.authHeader) {