@skyramp/mcp 0.0.64-rc.1 → 0.0.64-rc.3

package/build/index.js

@@ -32,6 +32,7 @@ import { registerOneClickTool } from "./tools/one-click/oneClickTool.js";
 import { registerAnalysisResources } from "./resources/analysisResources.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { initCheck } from "./utils/initAgent.js";
+import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
 const server = new McpServer({
     name: "Skyramp MCP Server",
     version: "1.0.0",
@@ -51,7 +52,9 @@ const server = new McpServer({
 
 ## Rules
 - NEVER show CLI commands. ALWAYS use the MCP tools provided.
-- For UI and E2E tests, use the trace collection start/stop tools.
+- For UI and E2E tests, there are TWO recording modes:
+  1. **AI-driven recording** (default): Use the browser_* tools (browser_navigate, browser_click, etc.) to record interactions, then call skyramp_export_zip to export the trace, then call skyramp_ui_test_generation with the zip path.
+  2. **Manual recording**: ONLY when the user explicitly says "manual recording", "record myself", "I will interact", or "Docker trace" — use skyramp_start_trace_collection / skyramp_stop_trace_collection to let the user interact with the browser themselves.
 - When the user asks to comprehensively, thoroughly, or deeply test a specific endpoint: MUST call \`skyramp_one_click_tool\` with workflow \`test_given_endpoint_comprehensively\` first. Do NOT self-orchestrate the steps manually.
 - When the user asks to scan the full repo, recommend, generate, and execute top N tests: MUST call \`skyramp_one_click_tool\` with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.
 
@@ -103,10 +106,12 @@ Before calling ANY test generation tool, you MUST follow this flow:
 5. **CRITICAL — scenario generation**: When calling \`skyramp_scenario_test_generation\`, ALWAYS pass:
    - \`baseURL\`: The full base URL from \`api.baseUrl\` (e.g., \`http://localhost:3000\`). This determines the scheme, host, and port in the generated trace. Without it, the trace defaults to https:443 which is almost always wrong for local development.
    - \`authHeader\`: Which HTTP header carries the auth credential. Get it from \`api.authHeader\` in workspace config. Examples: \`Authorization\` (Bearer/Token auth), \`X-Api-Key\` (API key auth), \`Cookie\` (session/cookie auth like NextAuth). Pass \`""\` to skip auth entirely (unauthenticated endpoints or \`api.authType: "none"\`).
-   - \`authScheme\`: Only when \`authHeader\` is \`Authorization\`. The prefix before the token (e.g., \`"Bearer"\` → \`Authorization: Bearer <token>\`). Common values: \`"Bearer"\`, \`"Basic"\`, \`"Token"\`. Leave empty if the API uses raw tokens with no prefix. Ignored for non-Authorization headers. **Derive from**: (1) OpenAPI spec \`securitySchemes\`/\`securityDefinitions\`, (2) source code auth middleware (\`passport.use\`, \`jwt.verify\`, header parsing logic), (3) workspace \`api.authType\`. **Do NOT guess.**
-   - \`authToken\`: The full header value, used verbatim. When omitted, \`SKYRAMP_PLACEHOLDER_TOKEN\` is auto-generated (combined with \`authScheme\` for Authorization headers). Only provide when the header needs a specific format — e.g., \`"session=${AUTH_PLACEHOLDER_TOKEN}"\` for Cookie. For Authorization headers, use \`authScheme\` instead. **Do NOT fabricate token values.**
+   - \`authScheme\`: Only when \`authHeader\` is \`Authorization\`. The prefix before the token (e.g., \`"Bearer"\` → \`Authorization: Bearer <token>\`). **Derive from**: (1) OpenAPI spec \`securitySchemes\`/\`securityDefinitions\`, (2) source code auth middleware, (3) workspace \`api.authType\`. **Do NOT guess.**
+   - \`authToken\`: The full header value, used verbatim. When omitted, \`SKYRAMP_PLACEHOLDER_TOKEN\` is auto-generated. Only provide when the header needs a specific format (e.g., \`"session=${AUTH_PLACEHOLDER_TOKEN}"\` for Cookie). **Do NOT fabricate token values.**
    - \`apiSchema\` is OPTIONAL — omit it for code-first apps without OpenAPI specs.
-6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`, ALSO pass \`authHeader\` and the same auth parameters used in scenario generation (\`authScheme\` for Authorization headers, or \`authToken\` for non-Authorization headers).
+6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`:
+   - If workspace has \`api.authType\` set: omit auth params entirely — passing auth here 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\`).
 7. **If the workspace file does not exist**, or the needed values (language, framework, outputDir) are missing from the workspace config, ASK the user which language and framework they want before calling the tool.
 8. The user can always override workspace defaults by explicitly specifying values in their request.
 `,
@@ -160,6 +165,7 @@ const prompts = [
     registerStartTraceCollectionPrompt,
     registerTestHealthPrompt,
     registerRecommendTestsPrompt,
+    registerTraceRecordingPrompt,
 ];
 if (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
     prompts.push(registerTestbotPrompt);
@@ -213,6 +219,10 @@ if (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
     logger.info("TestBot tools enabled via SKYRAMP_FEATURE_TESTBOT");
 }
 infrastructureTools.forEach((registerTool) => registerTool(server));
+// Register Playwright browser tools (trace recording via browser automation)
+registerPlaywrightTools(server).catch((err) => {
+    logger.error("Failed to register Playwright tools", { error: err });
+});
 // Global error handlers for crash telemetry
 process.on("uncaughtException", async (error) => {
     // Don't send analytics for EPIPE errors
@@ -245,8 +255,15 @@ async function main() {
             return;
         isShuttingDown = true;
         logger.info(`Parent process disconnected (${event}). Cleaning up and exiting...`);
-        server.close().finally(() => {
-            process.exit(0);
+        // Shut down Playwright browser before exiting
+        const playwrightService = getPlaywrightTraceService();
+        const cleanupPlaywright = playwrightService
+            ? playwrightService.shutdown().catch(() => { })
+            : Promise.resolve();
+        cleanupPlaywright.finally(() => {
+            server.close().finally(() => {
+                process.exit(0);
+            });
         });
     };
     process.stdin.on("end", () => handleParentDisconnect("stdin end"));

package/build/playwright/PlaywrightTraceService.js

@@ -0,0 +1,74 @@
+/**
+ * Service that manages a Playwright TraceRecordingBackend instance,
+ * exposing browser tools + skyramp_export_zip for use by the Skyramp MCP.
+ *
+ * The Playwright fork is CJS; this project is ESM. We use createRequire
+ * to bridge the module systems.
+ */
+import { createRequire } from "module";
+import { logger } from "../utils/logger.js";
+export class PlaywrightTraceService {
+    _backend = null;
+    _tools = [];
+    _options;
+    constructor(options) {
+        this._options = options || {};
+    }
+    async initialize() {
+        if (this._backend) {
+            logger.info("PlaywrightTraceService already initialized");
+            return;
+        }
+        try {
+            // Dynamic require of CJS Playwright module from ESM context
+            const require = createRequire(import.meta.url);
+            const { TraceRecordingBackend } = require("playwright/lib/mcp/skyramp");
+            this._backend = new TraceRecordingBackend({
+                headless: this._options.headless,
+                outputDir: this._options.outputDir || process.cwd(),
+            });
+            // Initialize with a synthetic client info
+            await this._backend.initialize({
+                name: "skyramp-mcp",
+                version: "1.0.0",
+                roots: [],
+                timestamp: Date.now(),
+            });
+            this._tools = await this._backend.listTools();
+            logger.info(`PlaywrightTraceService initialized with ${this._tools.length} tools`);
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            logger.error(`Failed to initialize PlaywrightTraceService: ${msg}`);
+            throw error;
+        }
+    }
+    isInitialized() {
+        return this._backend !== null;
+    }
+    getTools() {
+        return this._tools;
+    }
+    async callTool(name, args) {
+        if (!this._backend) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: "### Error\nPlaywright trace service not initialized. This is an internal error.",
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return this._backend.callTool(name, args);
+    }
+    async shutdown() {
+        if (this._backend) {
+            this._backend.serverClosed?.();
+            this._backend = null;
+            this._tools = [];
+            logger.info("PlaywrightTraceService shut down");
+        }
+    }
+}

package/build/playwright/index.js

@@ -0,0 +1,3 @@
+export { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
+export { registerPlaywrightTools, getPlaywrightTraceService, } from "./registerPlaywrightTools.js";
+export { registerTraceRecordingPrompt } from "./traceRecordingPrompt.js";

package/build/playwright/registerPlaywrightTools.js

@@ -0,0 +1,117 @@
+/**
+ * Registers all Playwright browser tools (+ skyramp_export_zip) as passthrough
+ * tools in the Skyramp MCP server, delegating calls to PlaywrightTraceService.
+ */
+import { z } from "zod";
+import { logger } from "../utils/logger.js";
+import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
+let _service = null;
+export function getPlaywrightTraceService() {
+    return _service;
+}
+export async function registerPlaywrightTools(server, options) {
+    _service = new PlaywrightTraceService(options);
+    try {
+        await _service.initialize();
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        logger.error(`Failed to initialize Playwright tools — browser tools will not be available: ${msg}`);
+        _service = null;
+        return;
+    }
+    const tools = _service.getTools();
+    logger.info(`Registering ${tools.length} Playwright browser tools`);
+    // Only expose essential browser tools to reduce LLM confusion.
+    // The full set (23 tools) overwhelms the LLM and causes it to use
+    // browser_evaluate/browser_run_code instead of the simpler tools.
+    const ESSENTIAL_TOOLS = new Set([
+        'browser_navigate',
+        'browser_snapshot',
+        'browser_click',
+        'browser_type',
+        'browser_select_option',
+        'browser_press_key',
+        'browser_hover',
+        'browser_tabs',
+        'browser_navigate_back',
+        'browser_wait_for',
+        'browser_take_screenshot',
+        'skyramp_export_zip',
+    ]);
+    const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));
+    logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);
+    for (const tool of filteredTools) {
+        const zodSchema = jsonSchemaToZod(tool.inputSchema);
+        server.registerTool(tool.name, {
+            description: tool.description || `Playwright tool: ${tool.name}`,
+            inputSchema: zodSchema,
+        }, async (params) => {
+            if (!_service?.isInitialized()) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "### Error\nPlaywright browser tools are not available. The service failed to initialize.",
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return _service.callTool(tool.name, params);
+        });
+    }
+    logger.info(`Registered ${filteredTools.length} Playwright tools: ${filteredTools.map((t) => t.name).join(", ")}`);
+}
+function jsonSchemaToZod(schema) {
+    const properties = schema.properties || {};
+    const required = new Set(schema.required || []);
+    const shape = {};
+    for (const [key, prop] of Object.entries(properties)) {
+        let field;
+        switch (prop.type) {
+            case "string":
+                field = prop.enum
+                    ? z.enum(prop.enum)
+                    : z.string();
+                break;
+            case "number":
+            case "integer":
+                field = z.number();
+                break;
+            case "boolean":
+                field = z.boolean();
+                break;
+            case "array":
+                field = z.array(prop.items ? jsonSchemaPropertyToZod(prop.items) : z.unknown());
+                break;
+            default:
+                field = z.unknown();
+        }
+        if (prop.description)
+            field = field.describe(prop.description);
+        if (prop.default !== undefined)
+            field = field.default(prop.default);
+        if (!required.has(key))
+            field = field.optional();
+        shape[key] = field;
+    }
+    return z.object(shape);
+}
+function jsonSchemaPropertyToZod(prop) {
+    switch (prop.type) {
+        case "string":
+            return prop.enum
+                ? z.enum(prop.enum)
+                : z.string();
+        case "number":
+        case "integer":
+            return z.number();
+        case "boolean":
+            return z.boolean();
+        case "array":
+            return z.array(prop.items ? jsonSchemaPropertyToZod(prop.items) : z.unknown());
+        default:
+            return z.unknown();
+    }
+}

package/build/playwright/traceRecordingPrompt.js

@@ -0,0 +1,54 @@
+/**
+ * MCP prompt that guides the LLM through the Playwright-based trace recording
+ * and Skyramp test generation flow.
+ */
+import { logger } from "../utils/logger.js";
+export function registerTraceRecordingPrompt(server) {
+    logger.info("Registering trace recording prompt");
+    server.registerPrompt("skyramp_trace_recording_prompt", {
+        description: "Guide for recording browser interactions as a Skyramp trace and generating UI tests",
+        argsSchema: {},
+    }, () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `## Skyramp Trace Recording & UI Test Generation
+
+You have access to Playwright browser tools that let you interact with web applications.
+Use these tools to record a trace of browser interactions, then generate a Skyramp UI test from that trace.
+
+### Flow
+
+1. **Navigate**: ALWAYS call \`browser_navigate\` with the target URL as the very first step, even if the browser seems to already be on that page. This ensures a clean state.
+2. **Understand the page**: Call \`browser_snapshot\` to see the current page state (ARIA tree).
+3. **Interact**: Use \`browser_click\`, \`browser_type\`, \`browser_select_option\`, \`browser_press_key\`, etc. to perform the user interactions described in the prompt.
+4. **Repeat steps 2-3** until all interactions are complete.
+5. **Export the trace**: Call \`skyramp_export_zip\` with an output path (e.g. \`skyramp_export.zip\`). This produces a zip containing the JSONL trace and HAR network recording.
+6. **Generate the test**: Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute path of the zip file from step 5.
+
+### Tips
+- If a \`browser_click\` or \`browser_type\` fails because the element reference is stale (page updated), call \`browser_snapshot\` to refresh the page state and retry.
+- Use \`browser_snapshot\` liberally — it helps you understand what elements are available.
+- The trace automatically deduplicates retries: if you navigate back to the start URL and redo steps, only the last complete attempt is exported.
+- After generating the test, the tool will suggest running \`skyramp_modularization\` for code quality.
+- **Dropdown/Select components**: For custom dropdowns (Radix, MUI, etc.) that show as \`combobox\` in the snapshot, do NOT use \`browser_select_option\` — it only works on native \`<select>\` elements. Instead: (1) click the combobox to open the dropdown, (2) call \`browser_snapshot\` to see the options in a \`listbox\`, (3) click the desired \`option\`. This three-step pattern is required for all custom dropdown components.
+- **Always take a snapshot after each interaction** that changes the page (click, form submit, navigation) to see the updated state before proceeding.
+
+### Critical rules for clicking
+- **NEVER click container/wrapper divs** (e.g. elements with "container" in their test-id). Always click the actual interactive element inside: a \`button\`, \`link\`, or \`input\`.
+- When the snapshot shows a container with a button inside, click the **button**, not the container. For example, if you see \`div "add-order-products-container" > button "Add"\`, click the button "Add", not the container.
+- To submit forms, click the submit \`button\` (e.g. "Add Order", "Submit"), never the form container.
+- After selecting a product from a dropdown, click the "Add" button to confirm, not the surrounding container.
+
+### Important
+- Do NOT ask the user before calling \`skyramp_export_zip\` — call it automatically as the final step.
+- Do NOT write JSONL or HAR files manually — the export tool handles everything.
+- Do NOT reuse existing zip files from previous sessions — always record fresh.
+`,
+                },
+            },
+        ],
+    }));
+}

package/build/prompts/startTraceCollectionPrompts.js

@@ -12,11 +12,13 @@ export function registerStartTraceCollectionPrompt(mcpServer) {
                 content: {
                     type: "text",
                     text: `
-**General information about Skyramp's trace collection:**
+**MANUAL Trace Collection (Docker-based):**
+This is for MANUAL recording where the USER interacts with the browser themselves. Use this ONLY when the user explicitly requests "manual recording", "record myself", "I will interact", or "Docker trace". For AI-driven recording (where the agent drives the browser), use the browser_* tools and skyramp_export_zip instead.
+
 * You can start a Skyramp trace session to capture network traffic from an active terminal window and for activity within a browser.
 * Once you start a Skyramp trace session, you can stop it any time. Once stopped, a new session will be required to start a new trace collection.
 * Please refer to the Skyramp documentation at https://www.skyramp.dev/docs/concepts/trace-collection for more details on trace collection.
-* Once you have all the data call the start trace generation tool to start the trace collection.
+* Once you have all the data call the stop trace collection tool to save the captured data.
 * Always ask user if they want to enable playwright for trace collection.
 
 **Playwright Configuration Options:**

package/build/prompts/test-recommendation/recommendationSections.js

@@ -1,5 +1,5 @@
 export const MAX_TESTS_TO_GENERATE = 3;
-export const MAX_RECOMMENDATIONS = 10;
+export const MAX_RECOMMENDATIONS = 20;
 export const MAX_CRITICAL_TESTS = 3;
 function serializeAuthCallParams(params) {
     const parts = [`authHeader: "${params.authHeader}"`];
@@ -81,11 +81,11 @@ Choose based on what adds the most value for this PR's changes.
 relationships in the code. If the pre-drafted scenarios don't match the real data model,
 replace them with accurate ones.
 ${isUIOnlyPR ? `
-**UI-only PR** — no backend changes. UI and E2E tests are most relevant.
-Without Playwright traces, list as additionalRecommendations with trace recording instructions.
+**UI-only PR** — no backend changes. UI tests are most relevant.
+Use Playwright browser tools to auto-record traces and generate UI tests.
 ` : `
-When no Playwright trace exists, still recommend E2E/UI tests with instructions for
-recording a trace using \`skyramp_start_trace_collection\` with \`playwright: true\`.
+When no Playwright trace exists, use the Playwright browser tools (\`browser_navigate\`,
+\`browser_click\`, etc.) to record a trace, then export via \`skyramp_export_zip\` for UI tests.
 `}
 **No duplicate coverage.** If an existing test already covers an endpoint + test type,
 recommend a different test that adds new coverage.`;
@@ -151,7 +151,16 @@ To skip auth for unauthenticated endpoints, pass \`authHeader: ""\`.`;
         authGuidance = `**Auth Header:** \`${authHeaderValue}\` is a non-Authorization header — a placeholder token is auto-generated. Just pass \`authHeader\` — do NOT pass \`authScheme\` (it is only for Authorization headers and will be ignored).
 To skip auth for unauthenticated endpoints, pass \`authHeader: ""\`.`;
     }
+    const hasWorkspaceAuthType = !!authTypeValue && authTypeValue !== "none";
     const authCallParams = serializeAuthCallParams(authParams);
+    // For skyramp_integration_test_generation with scenarioFile: omit auth entirely when workspace
+    // has authType (workspace handles generation-time auth). Without authType, pass authHeader only.
+    // NOTE: scenario generation always uses full authCallParams so auth is embedded in the test file
+    // and the executor sends the correct Authorization header at run time.
+    const authHeaderOnlyParams = serializeAuthCallParams({ authHeader: authParams.authHeader });
+    const integrationAuthNote = hasWorkspaceAuthType
+        ? `omit auth params entirely — workspace \`api.authType: "${authTypeValue}"\` handles it.`
+        : `pass \`${authHeaderOnlyParams}\` only (no \`authScheme\`).`;
     const authHeaderLine = noAuth
         ? `**No Auth (from workspace config):** Workspace indicates no authentication. **Verify independently** — if you find auth in the OpenAPI spec or source code, override with the correct \`authHeader\` and \`authScheme\`.`
         : `**Auth params:** \`${authCallParams}\` — pass to EVERY tool call below.`;
@@ -177,7 +186,7 @@ ${authGuidance}
    Use unique names with timestamp suffix to avoid conflicts on re-runs.
    For GET/PUT/DELETE with path IDs, use a placeholder — chaining resolves the real ID.
 2. Produces a \`scenario_<name>.json\` in the same \`outputDir\` as the test files (not \`.skyramp/\`).
-3. Call \`skyramp_integration_test_generation\` with \`scenarioFile\` AND \`${authCallParams}\`.
+3. Call \`skyramp_integration_test_generation\` with \`scenarioFile\`: ${integrationAuthNote}
    Do NOT pass \`chainingKey\` — defaults to \`response.id\`. After generation, the testbot
    will verify and fix path param chaining in the generated test.
 
@@ -198,12 +207,18 @@ ${PATH_PARAM_UUID_GUIDANCE}
 - Both — use when the service boundary is both a provider (owns an API) and a consumer (calls a downstream API).
 - Neither (default) — use only when the role is ambiguous or no spec is available.
 
-**For UI tests (no Playwright recording):**
-1. \`skyramp_start_trace_collection\` (playwright: true)
-2. Perform browser steps
-3. \`skyramp_stop_trace_collection\`
-4. \`skyramp_ui_test_generation\` with playwright zip
+**For UI tests:**
+1. \`browser_navigate\` to the target URL (from workspace \`api.baseUrl\`)
+2. \`browser_snapshot\` to see the page (ARIA tree)
+3. Interact using \`browser_click\`, \`browser_type\`, \`browser_fill_form\`, etc.
+4. \`browser_snapshot\` after each interaction that changes the page
+5. \`skyramp_export_zip\` with an **absolute** output path: \`<repositoryPath>/.skyramp/<test_name>_trace.zip\`
+6. \`skyramp_ui_test_generation\` with \`playwrightInput\` = the **absolute** path of the exported zip
 
-**For E2E tests:**
-Same trace flow, pass both trace file and playwright zip to \`skyramp_e2e_test_generation\`.`;
+Tips: For custom dropdowns (Radix, MUI): click combobox → snapshot → click option (NOT \`browser_select_option\`).
+
+**For E2E tests (mixed PR — both backend and frontend changed):**
+Only generate when pre-existing backend trace \`.json\` AND Playwright \`.zip\` both exist in the repo.
+Use them directly with \`skyramp_e2e_test_generation\`.
+If traces are missing, skip E2E and add to \`additionalRecommendations\` with instructions to record them first.`;
 }

package/build/prompts/test-recommendation/test-recommendation-prompt.js

@@ -44,12 +44,25 @@ function computeTiebreakerSeed(endpoints, diffFiles) {
     return crypto.createHash("sha256").update(canonical).digest("hex").slice(0, 8);
 }
 // ── Execution Plan (replaces pre-ranked + scenarios + heuristic sections) ──
-function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, authSchemeSnippet, seed, endpointCount, isUIOnlyPR) {
+function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges = false, hasTraces = false) {
     const generateItems = scored.slice(0, Math.min(maxGen, scored.length));
     const additionalItems = scored.slice(maxGen, topN);
     const authRef = authHeaderValue
         ? `, authHeader: "${authHeaderValue}"${authSchemeSnippet}`
         : `, authHeader: <check OpenAPI securitySchemes or auth middleware; "" if confirmed unauthenticated>`;
+    const hasWorkspaceAuthType = !!authTypeValue && authTypeValue !== "none";
+    // For skyramp_scenario_test_generation: always embed full auth so the generated test file
+    // includes the correct Authorization header at execution time.
+    // The workspace authType conflict only applies to skyramp_integration_test_generation (not scenario gen).
+    const scenarioAuthRef = authRef;
+    // For skyramp_integration_test_generation with scenarioFile:
+    // - If workspace has authType set: omit auth entirely — workspace handles Bearer prefix.
+    // - If no authType: pass authHeader only (no authScheme).
+    const authHeaderOnlyRef = hasWorkspaceAuthType
+        ? ""
+        : authHeaderValue
+            ? `, authHeader: "${authHeaderValue}"`
+            : `, authHeader: <check OpenAPI securitySchemes or auth middleware; "" if confirmed unauthenticated>`;
     const generateBlocks = generateItems.map((item, i) => {
         const rank = i + 1;
         const s = item.scenario;
@@ -63,7 +76,7 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
                 : "";
             return (`**#${rank} — GENERATE** | ${testType} | ${s.category} | priority=${item.priority} | ${item.novelty}\n` +
                 `${step.method} ${step.path} → ${step.expectedStatusCode}\n` +
-                `Tool: skyramp_contract_test_generation({ endpointURL: "${endpointURL}", method: "${step.method}"${authRef}${dataParam} })\n` +
+                `Tool: skyramp_contract_test_generation({ endpointURL: "${endpointURL}", method: "${step.method}"${authRef}${dataParam} })\n` + // contract tests always use full authRef
                 `From source: authScheme (OpenAPI securitySchemes or auth middleware)${isBodyMethod ? "; requestData field shapes" : ""}`);
         }
         else {
@@ -81,7 +94,7 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
                 const dataParam = isBodyMethod
                     ? `, requestBody: <${st.method} ${st.path} body from source code schemas>`
                     : "";
-                return `  skyramp_scenario_test_generation({ scenarioName: "${s.scenarioName}", destination: "${s.scenarioName}", baseURL: "${baseUrl}", method: "${st.method}", path: "${st.path}", statusCode: ${st.expectedStatusCode}${authRef}${dataParam} })`;
+                return `  skyramp_scenario_test_generation({ scenarioName: "${s.scenarioName}", destination: "${s.scenarioName}", baseURL: "${baseUrl}", method: "${st.method}", path: "${st.path}", statusCode: ${st.expectedStatusCode}${scenarioAuthRef}${dataParam} })`;
             }).join("\n");
             const prereqNote = s.category === "new_endpoint"
                 ? `\nPrerequisite discovery (MANDATORY for new_endpoint): Before executing these tool calls, read the source code for the new endpoint's request body. Look for FK fields (e.g. \`product_id\`, \`user_id\`, \`order_id\`). For each FK field found, prepend one \`skyramp_scenario_test_generation\` call to create that prerequisite resource first, then chain its \`id\` into the dependent step. If no FK fields exist, proceed with the steps above as-is.`
@@ -91,13 +104,21 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
                 `${stepLines}\n` +
                 `Tool calls:\n` +
                 `${toolCalls}\n` +
-                `  skyramp_integration_test_generation({ scenarioFile: "scenario_${s.scenarioName}.json"${authRef} })\n` +
+                `  skyramp_integration_test_generation({ scenarioFile: "scenario_${s.scenarioName}.json"${authHeaderOnlyRef} })\n` +
                 `From source: requestBody shapes for POST/PUT/PATCH steps; responseBody shapes; authScheme` +
                 prereqNote);
         }
     }).join("\n\n");
+    // For mixed PRs, always reserve slots for UI and E2E recommendations regardless of whether
+    // traces already exist — the user can record them later or the bot can record during the run.
+    const needsE2ESlot = hasFrontendChanges && !isUIOnlyPR;
+    const needsUISlot = hasFrontendChanges && !isUIOnlyPR;
+    const frontendSlots = (needsE2ESlot ? 1 : 0) + (needsUISlot ? 1 : 0);
+    const backendAdditionalItems = frontendSlots > 0
+        ? additionalItems.slice(0, Math.max(additionalItems.length - frontendSlots, 0))
+        : additionalItems;
     // Additional items — compact listing, no tool calls needed
-    const additionalLines = additionalItems.map((item, i) => {
+    const additionalLines = backendAdditionalItems.map((item, i) => {
         const rank = maxGen + i + 1;
         const s = item.scenario;
         const testType = s.testType ?? (s.steps.length === 1 ? "contract" : "integration");
@@ -106,17 +127,30 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
             : `Scenario: ${s.scenarioName} (${s.steps.map(st => `${st.method} ${st.path}`).join(" → ")})`;
         return `#${rank} [ADDITIONAL] | ${testType} | ${s.category} | priority=${item.priority} | ${item.novelty}\n  ${target}\n  Validates: ${s.description}`;
     }).join("\n\n");
-    const preRankedTotal = scored.length;
-    const supplementCount = topN - preRankedTotal;
+    const uiSlotLine = needsUISlot ? (() => {
+        const rank = maxGen + backendAdditionalItems.length + 1;
+        const traceNote = hasTraces
+            ? "Use an existing Playwright `.zip` trace from the repo."
+            : "Record a trace using `browser_navigate` + `browser_snapshot` + `skyramp_export_zip`, then call `skyramp_ui_test_generation`.";
+        return `\n\n#${rank} [ADDITIONAL] | UI | workflow | priority=HIGH | new\n  Scenario: ui-interaction-for-changed-components (frontend files changed in this diff)\n  Validates: Component-level interaction flow for the changed UI — derive the scenario name and steps from the actual changed frontend files. ${traceNote}`;
+    })() : "";
+    const e2eSlotLine = needsE2ESlot ? (() => {
+        const rank = maxGen + backendAdditionalItems.length + (needsUISlot ? 1 : 0) + 1;
+        const traceNote = hasTraces
+            ? "Call `skyramp_e2e_test_generation` with the discovered trace/recording files."
+            : "No traces exist yet — record a backend trace via `skyramp_start_trace_collection` + `skyramp_stop_trace_collection` and a UI trace via Playwright browser tools, then call `skyramp_e2e_test_generation`.";
+        return `\n\n#${rank} [ADDITIONAL] | E2E | workflow | priority=HIGH | new\n  Scenario: e2e-flow-for-changed-feature (frontend + backend files changed in this diff)\n  Validates: Full browser-level flow for the changed UI components end-to-end — derive the scenario name and steps from the actual changed frontend files. ${traceNote}`;
+    })() : "";
+    const supplementCount = topN - generateItems.length - backendAdditionalItems.length - frontendSlots;
     const supplementNote = supplementCount > 0
-        ? `\n**REQUIRED — You MUST add ${supplementCount} more to reach the total of ${topN}.** Draft them from endpoint interactions and source code patterns not yet covered. Use the same 5-dimension rubric and quality gate to assign priority (HIGH/MEDIUM/LOW), testType, and category. Do NOT produce fewer than ${topN} total.`
+        ? `\n**REQUIRED — You MUST add ${supplementCount} more to reach the total of ${topN}.** Draft them from endpoint interactions and source code patterns not yet covered. Use the same 5-dimension rubric and quality gate to assign priority (HIGH/MEDIUM/LOW), testType, and category.${hasFrontendChanges && !isUIOnlyPR ? " Since this PR has frontend changes, at least 1 of these should be a UI or E2E test targeting the changed components." : ""} Do NOT produce fewer than ${topN} total.`
         : "";
     return `## Execution Plan
 Seed: ${seed} | Endpoints: ${endpointCount} | Budget: ${generateItems.length} generate + ${Math.max(topN - generateItems.length, 0)} additional = ${topN} total
 
 **Step 1 — Source-Code Enrichment (MANDATORY before executing anything)**
 Read the source code for ALL changed files. Look for:
-- **Auth middleware** (passport, jwt.verify, authMiddleware, @requires_auth, Depends(get_current_user), @UseGuards, EnsureSessionDep, session middleware) — if found, override \`authHeader\` and \`authScheme\` in EVERY tool call even if workspace.yml says authType: none. A workspace misconfiguration must never cause tests to run unauthenticated against a protected API.
+- **Auth middleware** (passport, jwt.verify, authMiddleware, @requires_auth, Depends(get_current_user), @UseGuards, EnsureSessionDep, session middleware) — if found, override \`authHeader\` and \`authScheme\` in scenario and contract tool calls even if workspace.yml says authType: none. Exception: for \`skyramp_integration_test_generation\` with \`scenarioFile\`, omit auth params entirely if workspace has \`api.authType\` set (workspace handles it); if workspace has no \`authType\`, pass \`authHeader\` only.
 - Business rules and formulas (e.g. total_cost = compute * rate + memory * rate)
 - State transitions and domain constraints (e.g. budget cannot drop below current spend)
 - Validation logic (field constraints, cross-field dependencies)
@@ -178,7 +212,7 @@ ${generateBlocks || "  (no pre-ranked generate items — draft your own based on
 
 ### ADDITIONAL (list in additionalRecommendations in this order after Step 1 insertion)
 
-${additionalLines || "  (none pre-ranked)"}
+${additionalLines || "  (none pre-ranked)"}${uiSlotLine}${e2eSlotLine}
 ${supplementNote}
 
 **You MUST produce EXACTLY ${topN} total recommendations: ${generateItems.length} to generate + ${Math.max(topN - generateItems.length, 0)} as additionalRecommendations. Do NOT produce fewer. Generate recommendations now.**
@@ -218,7 +252,7 @@ export function buildRecommendationPrompt(analysis, analysisScope = "full_repo",
         ? `You are in **PR mode**. Maximize test coverage for the branch changes.
 Focus on tests that validate the changed fields, endpoints, and their interactions.
 ${isUIOnlyPR ? `\n**UI-only PR** — no backend changes. UI and E2E tests are most relevant.`
-            : hasFrontendChanges ? `\n**Mixed PR** — both frontend and backend changes detected.`
+            : hasFrontendChanges ? `\n**Mixed PR** — both frontend and backend changes detected. Backend and E2E/UI tests are both required.`
                 : ``}
 Output should be concise and immediately actionable.`
         : `You are in **Repo mode**. Comprehensive test strategy across all endpoints.`;
@@ -337,6 +371,13 @@ ${detailBlocks}
             const errorB = b.scenario.steps.some(s => s.interactionType === "error" || s.interactionType === "edge-case") ? 1 : 0;
             if (errorB !== errorA)
                 return errorB - errorA;
+            // Use locale-independent comparison to avoid runtime-locale non-determinism
+            const nameA = a.scenario.scenarioName;
+            const nameB = b.scenario.scenarioName;
+            if (nameA < nameB)
+                return -1;
+            if (nameA > nameB)
+                return 1;
             const hashA = parseInt(crypto.createHash("sha256").update(seed + a.scenario.scenarioName).digest("hex").slice(0, 8), 16);
             const hashB = parseInt(crypto.createHash("sha256").update(seed + b.scenario.scenarioName).digest("hex").slice(0, 8), 16);
             return hashA - hashB;
@@ -386,7 +427,7 @@ Do not churn recommendations without cause.
 `;
     }
     else if (scored.length > 0) {
-        mainSection = buildExecutionPlan(scored, maxGen, topN, analysis.apiEndpoints.baseUrl, authHeaderValue, authSchemeSnippet, seed, endpointCount, isUIOnlyPR);
+        mainSection = buildExecutionPlan(scored, maxGen, topN, analysis.apiEndpoints.baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges, hasTraces);
     }
     else {
         mainSection = `

package/build/prompts/testGenerationPrompt.js

@@ -198,7 +198,7 @@ Trace File:
 
 **CRITICAL: FOR A SINGLE SCENARIO CREATE A SINGLE SCENARIO FILE WITH EACH STEP AS A JSON OBJECT IN THE ARRAY.**
 
-**CRITICAL: SHOW STEPS TO START/STOP PLAYWRIGHT TRACE COLLECTION FOR UI TESTS. NEVER SHOW THE CLI COMMANDS.**
+**CRITICAL: For UI test trace collection, use the browser_* tools (browser_navigate, browser_click, browser_type, etc.) to interact with the application, then call skyramp_export_zip to export the trace zip. Do NOT use skyramp_start_trace_collection/skyramp_stop_trace_collection.**
             `,
                 },
             },