@skyramp/mcp 0.3.5 → 0.3.6-rc.2.ac20

package/build/recommendation/budgeters/shared.js

@@ -1,6 +1,6 @@
 import { TestType } from "../../types/TestTypes.js";
 import { inferScenarioType, prioritizeAttackSurfaceBundles } from "../diversity.js";
-import { externalDedupKey, scenarioCoverageKey, isAttackSurfaceSecurityBoundary, } from "../../prompts/test-recommendation/recommendationShared.js";
+import { externalDedupKeys, scenarioCoverageKeys, isAttackSurfaceSecurityBoundary, } from "../../prompts/test-recommendation/recommendationShared.js";
 import { logger } from "../../utils/logger.js";
 /**
  * Backend GENERATE slot count:
@@ -20,25 +20,39 @@ export function reservedUISlots(ctx) {
     return ctx.hasFrontendChanges && ctx.maxGenerate > 0 ? 1 : 0;
 }
 /**
- * Drop candidates whose method-aware resource+type is already covered by an
- * external test — except protected `bug_caught` / attack-surface scenarios,
- * which require semantic flaw coverage the external test may not provide.
+ * Split candidates by whether an external test already covers them. Protected
+ * `bug_caught` / attack-surface scenarios always count as uncovered — they
+ * require semantic flaw coverage the external test may not provide.
+ *
+ * A candidate is covered only when the set holds EVERY one of its keys. One
+ * match is not coverage: a scenario exercising two changed endpoints would lose
+ * the endpoint the external test does not reach (SKYR-4214). An empty key list
+ * carries no information, so it never removes anything.
+ *
+ * The covered group is held back, not discarded. `runBudget` moves it into
+ * ADDITIONAL when GENERATE's backend half would otherwise be empty (SKYR-4024),
+ * and records it as dropped, with a reason, when it does not.
  */
-function applyExternalDedup(ranked, externalCoverage) {
+function partitionByExternalCoverage(ranked, externalCoverage) {
     if (externalCoverage.size === 0)
-        return ranked;
-    return ranked.filter((item) => {
-        const key = externalDedupKey(item.scenario);
-        if (externalCoverage.has(key)) {
-            if (item.scenario.category === "bug_caught" || isAttackSurfaceSecurityBoundary(item.scenario)) {
-                logger.info(`External dedup: preserving "${item.scenario.scenarioName}" (${key}) — protected bug/attack-surface scenario requires semantic flaw coverage`);
-                return true;
-            }
-            logger.info(`External dedup: skipping "${item.scenario.scenarioName}" (${key}) — covered by external test`);
-            return false;
+        return { uncovered: ranked, covered: [] };
+    const uncovered = [];
+    const covered = [];
+    for (const item of ranked) {
+        const keys = externalDedupKeys(item.scenario);
+        if (keys.length === 0 || !keys.every((key) => externalCoverage.has(key))) {
+            uncovered.push(item);
+            continue;
         }
-        return true;
-    });
+        if (item.scenario.category === "bug_caught" || isAttackSurfaceSecurityBoundary(item.scenario)) {
+            logger.info(`External dedup: preserving "${item.scenario.scenarioName}" (${keys.join(", ")}) — protected bug/attack-surface scenario requires semantic flaw coverage`);
+            uncovered.push(item);
+            continue;
+        }
+        logger.info(`External dedup: "${item.scenario.scenarioName}" (${keys.join(", ")}) covered by an external test — eligible for the reserve`);
+        covered.push({ item, keys });
+    }
+    return { uncovered, covered };
 }
 /**
  * Shared budgeting pipeline. All Budgeters run the same external-dedup,
@@ -49,10 +63,11 @@ function applyExternalDedup(ranked, externalCoverage) {
  * diffExecutionPlan.ts exactly.
  */
 export function runBudget(ranked, ctx, pick) {
+    const dropped = [];
     const backend = backendGenerateCount(ctx);
     const uiSlots = reservedUISlots(ctx);
-    const deduped = applyExternalDedup(ranked, ctx.externalCoverage);
-    const slotOrdered = prioritizeAttackSurfaceBundles(deduped);
+    const { uncovered, covered } = partitionByExternalCoverage(ranked, ctx.externalCoverage);
+    const slotOrdered = prioritizeAttackSurfaceBundles(uncovered);
     // When UI slots are reserved, keep UI candidates out of the backend pick so the
     // reserved slot can always be filled below. Otherwise a high-ranked (e.g.
     // CRITICAL) UI candidate could be consumed by the backend pick on a mixed PR,
@@ -77,14 +92,77 @@ export function runBudget(ranked, ctx, pick) {
         chosen.add(item);
     }
     const generate = [...backendGenerate, ...uiGenerate];
-    // ADDITIONAL = everything not chosen for GENERATE, in rank order, capped at the
-    // remaining budget, minus any whose resource+type is already covered by GENERATE.
-    const generatedCoverage = new Set(generate.map((item) => scenarioCoverageKey(item.scenario)));
-    const additional = slotOrdered
-        .filter((it) => !chosen.has(it))
-        .slice(0, Math.max(0, ctx.maxTotal - generate.length))
-        .filter((item) => !generatedCoverage.has(scenarioCoverageKey(item.scenario)));
+    // SKYR-4024. A covered candidate is one an existing test already reaches, so
+    // generating a second test for it is wrong — maintenance updates the existing
+    // one. But dropping it outright removed it from the RECOMMENDATIONS too, and an
+    // empty GENERATE is authoritative downstream. The reserve surfaces it as
+    // ADDITIONAL instead. The emptiness test reads the backend half: on a mixed PR
+    // one UI candidate fills the reserved slot while every covered backend
+    // candidate would otherwise vanish.
+    //
+    // Two conditions keep the reserve shut where recommending nothing is right.
+    // Backend slots must exist, so a UI-only PR is left alone. And the PR must not
+    // touch a test file of its own: coverage is read from the working tree, and a
+    // test file without the Skyramp marker counts as external, so a PR that adds
+    // its own tests would have that coverage used as grounds to recommend
+    // duplicates of it.
+    const spendReserve = backendGenerate.length === 0 && backend > 0 && covered.length > 0 && !ctx.diffChangesTestFiles;
+    if (spendReserve) {
+        logger.info(`External dedup: GENERATE empty after dedup — recommending ${covered.length} held-back candidate(s) as ADDITIONAL rather than approving an empty plan`);
+    }
+    else if (covered.length > 0) {
+        // SKYR-4214. The reserve stayed shut, so these really are dropped — say so,
+        // with the reason, instead of leaving the agent an unexplained short list.
+        const reason = backendGenerate.length > 0
+            ? `the backend half of GENERATE is filled (${backendGenerate.length})`
+            : backend === 0
+                ? "no backend slots (UI-only PR)"
+                : "the PR changes test files of its own";
+        logger.info(`External dedup: dropping ${covered.length} covered candidate(s) — reserve shut because ${reason}`);
+        for (const { item, keys } of covered) {
+            dropped.push({
+                candidateId: item.candidateId,
+                reason: `covered by an external test (${keys.join(", ")})`,
+            });
+        }
+    }
+    // ADDITIONAL = everything not chosen for GENERATE, in rank order, minus any
+    // whose subject endpoints are ALL already covered by GENERATE, then capped at
+    // the remaining budget. All, not any: an item that also covers an endpoint no
+    // GENERATE item reaches is not a duplicate. An empty key list never removes
+    // an item.
+    //
+    // The duplicate filter runs BEFORE the cap. In the other order a duplicate
+    // took a slot and then vacated it, and nothing moved up: eval run
+    // 32543498147, fixture cc15-org-reviewer-role, filled 19 of a maxTotal of 20
+    // while 16 candidates carried the reason "beyond the maxTotal budget of 20".
+    // A candidate that is both a duplicate and past the cap now reports the
+    // duplicate — the stronger reason, and the only one that does not depend on
+    // where the cap happened to fall.
+    const additionalSource = spendReserve
+        ? [...slotOrdered, ...prioritizeAttackSurfaceBundles(covered.map((c) => c.item))]
+        : slotOrdered;
+    const notChosen = additionalSource.filter((it) => !chosen.has(it));
+    const remainingBudget = Math.max(0, ctx.maxTotal - generate.length);
+    const generatedCoverage = new Set(generate.flatMap((item) => scenarioCoverageKeys(item.scenario)));
+    const notDuplicate = notChosen.filter((item) => {
+        const keys = scenarioCoverageKeys(item.scenario);
+        if (keys.length === 0 || !keys.every((key) => generatedCoverage.has(key)))
+            return true;
+        dropped.push({
+            candidateId: item.candidateId,
+            reason: `covered by GENERATE (${keys.join(", ")})`,
+        });
+        return false;
+    });
+    const additional = notDuplicate.slice(0, remainingBudget);
+    for (const item of notDuplicate.slice(remainingBudget)) {
+        dropped.push({
+            candidateId: item.candidateId,
+            reason: `beyond the maxTotal budget of ${ctx.maxTotal}`,
+        });
+    }
     // Budgeting itself produces no demotions; the register-plan selection stage
     // (planRanker.selectPlan) fills this channel from discriminator verification.
-    return { generate, additional, reservedUISlots: uiSlots, demotions: [] };
+    return { generate, additional, reservedUISlots: uiSlots, demotions: [], dropped };
 }

package/build/recommendation/discriminators.js

@@ -281,9 +281,20 @@ function isNegativeAssertStep(step) {
     if (step?.expectedStatusCode === 404)
         return true;
     const assertions = [...toStringArray(step?.expectedResponseFields), ...toStringArray(step?.bodyMustInclude)];
-    return assertsEmptyOrZero(assertions);
+    return assertsEmptyOrZero(assertions, step?.responseBody);
 }
-function assertsEmptyOrZero(strings) {
+/**
+ * True when the step asserts an empty or zero result, reading the assertion
+ * strings AND `responseBody`. An EMPTY ARRAY body is itself the "no rows came
+ * back" assertion, and can be the only empty-result signal a step carries.
+ *
+ * `{}` deliberately does NOT count: an unspecified body is filled in as `{}`
+ * (ScenarioGenerationService), so it cannot be told apart from a body the agent
+ * never wrote. `isAssertStep` above already reads `{}` as asserting nothing.
+ */
+function assertsEmptyOrZero(strings, responseBody) {
+    if (Array.isArray(responseBody) && responseBody.length === 0)
+        return true;
     return strings.some((raw) => {
         const s = raw.toLowerCase();
         if (/\bcount\b/.test(s) && /\b0\b/.test(s))

package/build/recommendation/planRanker.d.ts

@@ -4,9 +4,9 @@ import { ScenarioCategory } from "../types/TestRecommendation.js";
 export interface RankOptions {
     /**
      * Categories that take the top carve-out tier ahead of everything else.
-     * Defaults to the `CATEGORY_PRIORITY === "CRITICAL"` categories (new_endpoint,
-     * bug_caught). Exposed so phase 2 can tune the carve-out WITHOUT reintroducing
-     * the agent's priority tag as a ranking input.
+     * Defaults to the `CATEGORY_PRIORITY === "CRITICAL"` categories (bug_caught only —
+     * new_endpoint is MEDIUM, not carved out). Exposed so phase 2 can tune the carve-out
+     * WITHOUT reintroducing the agent's priority tag as a ranking input.
      */
     carveOutCategories?: ScenarioCategory[];
     /**
@@ -32,9 +32,9 @@ export interface SelectPlanContext extends BudgetContext {
  * independent of input order (the final tiebreak is the stable `candidateId`).
  *
  * Ordering (highest first):
- *   1. Carve-out — bug_caught / CRITICAL-category scenarios (new_endpoint,
- *      bug_caught), preserving the protected-first convention of
- *      `roundRobinByType` / `prioritizeAttackSurfaceBundles`.
+ *   1. Carve-out — CRITICAL-category scenarios (bug_caught), preserving the
+ *      protected-first convention of `roundRobinByType` /
+ *      `prioritizeAttackSurfaceBundles`.
  *   2. Verified discriminators — candidates whose declared discriminator survived
  *      `validateDiscriminator` (marked via `verifiedDiscriminator`) float ahead of
  *      unverified peers in the same tier.

package/build/recommendation/planRanker.js

@@ -1,6 +1,6 @@
 import { CATEGORY_PRIORITY, PriorityTier } from "../types/TestRecommendation.js";
 import { diversityBalancedBudgeter } from "./budgeters/diversityBalancedBudgeter.js";
-import { parseRouteLine, normalizeDiffPath } from "../utils/routeParsers.js";
+import { collectChangedRouteLines, findStepOnChangedRoute } from "../utils/changedRoutes.js";
 const PRIORITY_RANK = {
     CRITICAL: 0,
     HIGH: 1,
@@ -14,9 +14,9 @@ const DEFAULT_CARVE_OUT_CATEGORIES = Object.keys(CATEGORY_PRIORITY).filter((cate
  * independent of input order (the final tiebreak is the stable `candidateId`).
  *
  * Ordering (highest first):
- *   1. Carve-out — bug_caught / CRITICAL-category scenarios (new_endpoint,
- *      bug_caught), preserving the protected-first convention of
- *      `roundRobinByType` / `prioritizeAttackSurfaceBundles`.
+ *   1. Carve-out — CRITICAL-category scenarios (bug_caught), preserving the
+ *      protected-first convention of `roundRobinByType` /
+ *      `prioritizeAttackSurfaceBundles`.
  *   2. Verified discriminators — candidates whose declared discriminator survived
  *      `validateDiscriminator` (marked via `verifiedDiscriminator`) float ahead of
  *      unverified peers in the same tier.
@@ -77,62 +77,7 @@ function categoryRank(candidate) {
     const tier = CATEGORY_PRIORITY[candidate.scenario?.category] ?? PriorityTier.LOW;
     return PRIORITY_RANK[tier];
 }
-/**
- * Extract method+path from every changed (`+`/`-`, non-header) line of a raw
- * unified diff. Reuses `parseRouteLine`, which already strips the leading
- * `+`/`-` marker and matches the same route-decorator patterns the endpoint
- * scanner does.
- */
-function collectChangedRouteLines(diffText) {
-    const routes = [];
-    let currentFile = "";
-    for (const line of diffText.split("\n")) {
-        // Track the current file from the unified-diff header so parseRouteLine
-        // gets the real path — its UI-component guard (UI_COMPONENT_EXT) depends
-        // on it, or a route-shaped line inside a .tsx/.jsx file (e.g. a client
-        // router registration) gets misparsed as a changed backend route.
-        if (line.startsWith("+++ ")) {
-            const spec = line.slice(4).trim().split("\t")[0];
-            currentFile = spec === "/dev/null" ? "" : normalizeDiffPath(spec);
-            continue;
-        }
-        if (line.startsWith("--- ") || line.startsWith("diff --git") || line.startsWith("index "))
-            continue;
-        if (!(line.startsWith("+") || line.startsWith("-")))
-            continue;
-        const parsed = parseRouteLine(line, currentFile);
-        if (parsed)
-            routes.push({ method: parsed.method, path: parsed.path });
-    }
-    return routes;
-}
-/**
- * Whether any step of `scenario` targets a method+path on the changed hunk.
- * Diff-extracted paths are local to the file's own router declaration (e.g.
- * "/suggestions"); scenario step paths are fully mounted (e.g.
- * "/api/recipes/suggestions") once drafted from a scanned/recovered endpoint.
- * A local path matches when the step path ends with it, so the cross-file
- * mount prefix difference (see recoverRemovedEndpointsFromBase, SKYR-4026)
- * doesn't prevent the match.
- */
+/** Whether any step of `scenario` targets a method+path on the changed hunk. */
 function scenarioOnChangedHunk(scenario, changedRoutes) {
-    if (changedRoutes.length === 0)
-        return false;
-    for (const step of scenario.steps ?? []) {
-        const stepMethod = (step.method ?? "").toUpperCase();
-        const stepPath = (step.path ?? "").replace(/\/+$/, "");
-        for (const route of changedRoutes) {
-            if (route.method.toUpperCase() !== stepMethod)
-                continue;
-            const routePath = route.path.replace(/\/+$/, "");
-            if (routePath === "") {
-                if (stepPath === "" || stepPath === "/")
-                    return true;
-                continue;
-            }
-            if (stepPath === routePath || stepPath.endsWith(routePath))
-                return true;
-        }
-    }
-    return false;
+    return !!findStepOnChangedRoute(scenario.steps, changedRoutes);
 }

package/build/services/AnalyticsService.d.ts

@@ -1,5 +1,12 @@
 import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 export declare class AnalyticsService {
+    /**
+     * Only the fields named here reach the analytics backend. The tool's own
+     * params are NOT forwarded wholesale: they carry the user's prompt, which is
+     * free text about a private codebase and has no business leaving the machine.
+     * Anything added here is sent verbatim -- PushToolEvent on the Go side does no
+     * redaction of its own -- so add a field only when it is safe to publish.
+     */
     static pushTestGenerationToolEvent(toolName: string, result: CallToolResult, params: Record<string, any>): Promise<void>;
     static pushMCPToolEvent(toolName: string, result: CallToolResult | undefined, params: Record<string, any>): Promise<void>;
     /**

package/build/services/AnalyticsService.js

@@ -40,9 +40,15 @@ async function safePushToolEvent(entryPoint, toolName, errorMessage, params) {
     }
 }
 export class AnalyticsService {
+    /**
+     * Only the fields named here reach the analytics backend. The tool's own
+     * params are NOT forwarded wholesale: they carry the user's prompt, which is
+     * free text about a private codebase and has no business leaving the machine.
+     * Anything added here is sent verbatim -- PushToolEvent on the Go side does no
+     * redaction of its own -- so add a field only when it is safe to publish.
+     */
     static async pushTestGenerationToolEvent(toolName, result, params) {
         const analyticsResult = {};
-        analyticsResult["prompt"] = params.prompt;
         analyticsResult["language"] = params.language;
         this.pushMCPToolEvent(toolName, result, analyticsResult);
     }

package/build/services/ModularizationService.js

@@ -28,10 +28,8 @@ The test file \`${params.testFile}\` will remain unchanged. No further action is
         let prompt = "";
         switch (testType) {
             case TestType.UI:
-                prompt = getModularizationPromptForUI(params.testFile);
-                break;
             case TestType.E2E:
-                prompt = getModularizationPromptForUI(params.testFile);
+                prompt = getModularizationPromptForUI(params.testFile, testType, params.language);
                 break;
             case TestType.INTEGRATION:
                 prompt = getModularizationPromptForIntegration(params.testFile);

package/build/services/TestDiscoveryService.d.ts

@@ -45,8 +45,6 @@ export declare class TestDiscoveryService {
     private readonly SUPPORTED_EXTENSIONS;
     private readonly MAX_CONCURRENT_OPERATIONS;
     private readonly MAX_EXTERNAL_FULL_REPO;
-    private readonly TEST_FILE_PATTERNS;
-    private readonly TEST_DIR_PATTERNS;
     /**
      * Discover all tests under testDir — both Skyramp-generated and external (user-written).
      * Uses fast-glob for cross-platform file scanning, then classifies discovered files

package/build/services/TestDiscoveryService.js

@@ -5,6 +5,7 @@ import { TestSource } from "../types/TestAnalysis.js";
 import { TestType } from "../types/TestTypes.js";
 import { buildPathSignatures } from "../utils/pathSignatures.js";
 import fg from "fast-glob";
+import { isDiscoveredTestFile } from "../utils/testFileClassification.js";
 export class TestDiscoveryService {
     EXCLUDED_DIRS = [
         "node_modules",
@@ -34,37 +35,6 @@ export class TestDiscoveryService {
     // In PR mode this hard limit is replaced by relevance-based partitioning which
     // naturally bounds the read set to files relevant to the changed endpoints.
     MAX_EXTERNAL_FULL_REPO = 100;
-    // Test file naming patterns — match against basename.
-    // Includes Skyramp-generated suffixes so that files like orders_smoke.py placed
-    // outside a recognized test directory are still discovered.
-    TEST_FILE_PATTERNS = [
-        /^test_.*\.(py|js|ts|rb|go|php)$/, // test_*.py, test_*.rb, test_*.go
-        /.*_test\.(py|ts|js|go|rs)$/, // *_test.py, *_test.go, *_test.rs
-        /.*\.test\.(ts|js|tsx|jsx)$/, // *.test.ts, *.test.js, *.test.tsx
-        /.*\..*spec\.(ts|js|tsx|jsx|rb)$/, // *.spec.ts, *.e2e-spec.ts, *.unit-spec.ts
-        /.*Test\.(java|kt|kts|cs|scala|swift|m)$/, // *Test.java, *Test.kt, *Test.m (ObjC)
-        /.*Tests\.(cs|swift|m)$/, // *Tests.cs, *Tests.swift, *Tests.m (ObjC)
-        /.*_spec\.rb$/, // *_spec.rb (RSpec)
-        /.*\.test\.php$/, // *.test.php
-        /.*Test\.php$/, // *Test.php (PHPUnit)
-        // Skyramp-generated test suffixes — must be matched even outside test dirs
-        /.*_(?:smoke|contract|fuzz|integration|load|e2e|ui)\.(py|ts|js|java|rb|go|cs|kt|kts|scala|swift|php|rs)$/i,
-    ];
-    // Directory patterns that signal test-owned files — works with both / and \ separators.
-    // Includes standard test dirs, snapshot dirs, and common helper/fixture dirs used by
-    // Playwright, Cypress, and other frameworks for page objects and support code.
-    TEST_DIR_PATTERNS = [
-        /[\\/]tests?[\\/]/,
-        /[\\/]__tests__[\\/]/,
-        /[\\/]__snapshots__[\\/]/, // Jest/Vitest snapshot directories
-        /[\\/]spec[\\/]/,
-        /[\\/]e2e[\\/]/,
-        /[\\/]cypress[\\/]/, // Cypress support, fixtures, plugins
-        /[\\/]playwright[\\/]/, // Playwright fixtures and helpers
-        /[\\/]page-?objects?[\\/]/, // page-objects/, page-object/, pageObjects/
-        /[\\/]fixtures[\\/](?!db[\\/]|seed[\\/]|migrations[\\/])/, // test fixture files (not db/seed/migration fixtures)
-        /[\\/]cypress[\\/]support[\\/]/, // Cypress support directory (scoped to avoid matching app support/ dirs)
-    ];
     /**
      * Discover all tests under testDir — both Skyramp-generated and external (user-written).
      * Uses fast-glob for cross-platform file scanning, then classifies discovered files
@@ -478,12 +448,7 @@ export class TestDiscoveryService {
      * or directory placement.
      */
     isExternalTestFile(filePath) {
-        const basename = path.basename(filePath);
-        if (this.TEST_FILE_PATTERNS.some(p => p.test(basename)))
-            return true;
-        if (this.TEST_DIR_PATTERNS.some(p => p.test(filePath)))
-            return true;
-        return false;
+        return isDiscoveredTestFile(filePath);
     }
     /**
      * Extract metadata from a test file

package/build/services/TestGenerationService.d.ts

@@ -44,6 +44,15 @@ export interface BaseTestParams {
  * empty-string edge (SKYR-3899).
  */
 export declare function deriveEffectiveFramework(language: string | undefined, framework: string | undefined): string;
+/** The files codegen reports it wrote — the block every generation result carries:
+ *
+ *     Successfully generated/updated tests files:
+ *     \t/abs/path/to/orders_integration_test.py
+ *
+ *  Read from the result rather than inferred from the filesystem, so a leftover from an
+ *  earlier attempt or a sibling written by another call is never mistaken for this call's
+ *  output. Empty when the block is absent (nothing to hand off). */
+export declare function generatedFilesFrom(result: string): string[];
 export declare abstract class TestGenerationService {
     protected client: SkyrampClient;
     constructor();
@@ -51,6 +60,13 @@ export declare abstract class TestGenerationService {
     protected validateInputs(params: BaseTestParams): CallToolResult;
     protected abstract buildGenerationOptions(params: BaseTestParams & Record<string, any>): any;
     protected abstract getTestType(): TestType | typeof MOCK_TYPE;
+    /**
+     * Whether this generation's codeReuse hand-off sequences skyramp_modularization
+     * before skyramp_reuse_code (routing: isModularizeFirstTarget). Subclasses that
+     * add their own post-generation steps consult this so modularization is
+     * instructed exactly once.
+     */
+    protected emitsModularizeFirstHandOff(params: BaseTestParams): boolean;
     protected handleApiAnalysis(params: BaseTestParams): Promise<CallToolResult | null>;
     private static readonly STANDARD_HEADERS;
     private static simpleWildcardMatch;

package/build/services/TestGenerationService.js

@@ -3,7 +3,7 @@ import fs from "fs";
 import { SkyrampClient } from "@skyramp/skyramp";
 import { analyzeOpenAPIWithGivenEndpoint } from "../utils/analyze-openapi.js";
 import { isAuthorizationHeaderName, KNOWN_AUTH_HEADERS, resolveAuthFromWorkspace, getWorkspaceSkipTLSVerify, getWorkspaceScopedQueryParams, mergeQueryParamsString, } from "../utils/workspaceAuth.js";
-import { extractPathname, resolveQueryParamsForPath, contributesNothing } from "../workspace/queryParamResolution.js";
+import { extractPathname, resolveQueryParamsForPath, contributesNothing, } from "../workspace/queryParamResolution.js";
 import { getPathParameterValidationError, OUTPUT_DIR_FIELD_NAME, PATH_PARAMS_FIELD_NAME, QUERY_PARAMS_FIELD_NAME, FORM_PARAMS_FIELD_NAME, validateParams, validatePath, validateRequestData, } from "../utils/utils.js";
 import { getEntryPoint } from "../utils/telemetry.js";
 import { getLanguageSteps } from "../utils/language-helper.js";
@@ -12,6 +12,8 @@ import { logger } from "../utils/logger.js";
 import { normalizeLanguageParams } from "../utils/normalizeParams.js";
 import { stageGeneratedPaths, resolveOutputDir } from "../utils/gitStaging.js";
 import { getTestsRepoDir } from "../utils/AnalysisStateManager.js";
+import { recordReuseHandOff } from "../tools/code-refactor/reuse-state.js";
+import { isModularizeFirstTarget } from "../utils/reuseRouting.js";
 /**
  * Derive the framework actually used for generation from the (normalized)
  * language + framework params. A blank/whitespace-only framework is treated as
@@ -35,10 +37,24 @@ export function deriveEffectiveFramework(language, framework) {
  * defaultQueryParams value into that path is not what the design intends
  * (SKYR-4050).
  */
-const SKIP_DEFAULT_QUERY_PARAMS_TEST_TYPES = new Set([
-    TestType.UI,
-    TestType.E2E,
-]);
+const SKIP_DEFAULT_QUERY_PARAMS_TEST_TYPES = new Set([TestType.UI, TestType.E2E]);
+/** The files codegen reports it wrote — the block every generation result carries:
+ *
+ *     Successfully generated/updated tests files:
+ *     \t/abs/path/to/orders_integration_test.py
+ *
+ *  Read from the result rather than inferred from the filesystem, so a leftover from an
+ *  earlier attempt or a sibling written by another call is never mistaken for this call's
+ *  output. Empty when the block is absent (nothing to hand off). */
+export function generatedFilesFrom(result) {
+    const m = /Successfully generated\/updated tests? files?:\s*\n((?:[ \t]+\S[^\n]*\n?)+)/i.exec(result);
+    if (!m)
+        return [];
+    return m[1]
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0 && path.isAbsolute(l));
+}
 export class TestGenerationService {
     client;
     constructor() {
@@ -74,6 +90,9 @@ export class TestGenerationService {
                 return apiAnalysisResult;
             }
             const result = await this.executeGeneration(generateOptions);
+            // The files this call wrote, as codegen reports them — the reuse hand-off is
+            // recorded per FILE (SKYR-4220).
+            const written = generatedFilesFrom(result);
             const testType = this.getTestType();
             const languageSteps = getLanguageSteps({
                 language: params.language || "",
@@ -83,12 +102,57 @@ export class TestGenerationService {
             // Orchestrate code optimization workflow based on flags
             let postGenerationMessage = "";
             if (params.codeReuse) {
-                // Only code reuse
-                postGenerationMessage += `
+                // Name the framework generation actually used, not the raw parameter:
+                // TS/JS derive to playwright when the caller omitted it, and
+                // skyramp_reuse_code requires framework to route correctly.
+                const effectiveFramework = deriveEffectiveFramework(params.language || "", params.framework);
+                const reuseArgs = `\`testFile\` set to the absolute path of the generated test file, \`language: "${params.language}"\`, \`testType: "${testType}"\`${effectiveFramework ? `, and \`framework: "${effectiveFramework}"\`` : ""}`;
+                // Modularize-first: fresh codegen carries no helper functions (each
+                // endpoint called once, each browser step inline), so modularization is
+                // what creates the named helpers that reuse then consolidates into the
+                // shared utils file. Emitted here, not in the testbot prompt, so the
+                // instruction exists only on runs that actually generated this test type
+                // and needs no hand-maintained step numbering.
+                if (this.emitsModularizeFirstHandOff(params)) {
+                    // SKYR-4220: record the hand-off at the site that emits it, under the same
+                    // condition, so skyramp_execute_test can refuse a test that skipped the pair
+                    // and the report can mark it — without ever owing it for a test that was not
+                    // told to run it. Keyed by the files this call wrote: a test generated into
+                    // the same directory without codeReuse owes nothing.
+                    await recordReuseHandOff(written, testType, params.language || "", effectiveFramework);
+                    // Browser tests: the assertion enhancer anchors new assertions to
+                    // selectors present in the test file, and after modularize → reuse
+                    // those selectors live in the utils file. So for UI the enhancer runs
+                    // FIRST, on the raw file; the extraction rules then keep every value
+                    // assertion in the test body. API enhancers key off response paths,
+                    // so integration keeps its validated modularize → reuse → enhance order.
+                    const enhanceFirst = testType === TestType.UI && !!params.enhanceAssertions;
+                    const steps = [
+                        ...(enhanceFirst
+                            ? [
+                                `Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated test file, \`testType: "${testType}"\`, and \`enhanceType: "generation"\`, and apply every instruction returned to that file — BEFORE modularization, while the file's selectors are still inline.`,
+                            ]
+                            : []),
+                        `Call \`skyramp_modularization\` with \`testFile\`, \`testType: "${testType}"\`, and \`isTraceBased: true\`, and apply the returned instructions — this extracts the test's steps into named helper functions, which is what makes cross-test reuse possible.`,
+                        `Immediately after writing the modularized file — as your very NEXT skyramp tool call — call \`skyramp_reuse_code\` with ${reuseArgs}. The modularization call does NOT count as this step: reuse is a separate tool and MUST be invoked even when you expect it to find nothing. Follow the returned steps to completion. Sibling tests offering nothing to reuse is a normal outcome — the returned steps still move THIS test's own helpers into the shared utils file and import them back, so the test file IS expected to change; finish those steps, then continue (do NOT retry).`,
+                    ];
+                    const ordering = enhanceFirst
+                        ? "three sub-steps, STRICTLY SEQUENTIAL (never in the same tool-call batch)"
+                        : "two sub-steps, STRICTLY SEQUENTIAL (never in the same tool-call batch), BOTH BEFORE `skyramp_enhance_assertions`";
+                    postGenerationMessage += `
+ Test generated successfully!
+
+⏭️**CRITICAL NEXT STEPS — ${ordering}**:
+${steps.map((text, i) => `${String.fromCharCode(97 + i)}. ${text}`).join("\n")}
+`;
+                }
+                else {
+                    postGenerationMessage += `
  Test generated successfully!
 
-⏭️**CRITICAL NEXT STEP**: Running code reuse analysis with skyramp_reuse_code tool.
+⏭️**CRITICAL NEXT STEP**: Run code reuse analysis by calling the skyramp_reuse_code tool with ${reuseArgs}.
 `;
+                }
             }
             else if (params.modularizeCode) {
                 // Check if test type should be modularized
@@ -210,6 +274,16 @@ The generated test file remains unchanged and ready to use as-is.
             ? { content: [], isError: false }
             : errList;
     }
+    /**
+     * Whether this generation's codeReuse hand-off sequences skyramp_modularization
+     * before skyramp_reuse_code (routing: isModularizeFirstTarget). Subclasses that
+     * add their own post-generation steps consult this so modularization is
+     * instructed exactly once.
+     */
+    emitsModularizeFirstHandOff(params) {
+        return (!!params.codeReuse &&
+            isModularizeFirstTarget(this.getTestType(), params.language));
+    }
     async handleApiAnalysis(params) {
         if (params.apiSchema && params.endpointURL && params.method === "") {
             try {
@@ -274,7 +348,9 @@ The generated test file remains unchanged and ready to use as-is.
     // KNOWN_AUTH_HEADERS is imported from workspaceAuth.ts — single source of truth
     // shared with trace-parser.ts for redaction. See workspaceAuth.ts for the full list.
     static simpleWildcardMatch(pattern, value) {
-        const regex = new RegExp("^" + pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") + "$");
+        const regex = new RegExp("^" +
+            pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*") +
+            "$");
         return regex.test(value);
     }
     static traceMatchesFilters(entry, include, exclude) {
@@ -421,7 +497,7 @@ The generated test file remains unchanged and ready to use as-is.
                 // authType handles the Authorization header implicitly — the Go CLI treats
                 // --auth-type and --auth-header as mutually exclusive, so clear authHeader
                 // when it's the standard Authorization header to avoid the conflict.
-                if (isAuthorizationHeaderName(generateOptions.authHeader || '')) {
+                if (isAuthorizationHeaderName(generateOptions.authHeader || "")) {
                     delete generateOptions.authHeader;
                 }
             }

package/build/services/containerEnv.js

@@ -106,23 +106,24 @@ export function buildContainerEnv(options, saveStoragePath, hostEnv = process.en
     // carrying as literals (SKYR-3862). Without this the container never sees
     // them and every generated login fails its guard.
     //
+    // Matched by prefix, like the service URLs above: a multi-credential
+    // `uiCredentials` input exports one keyed pair per credential —
+    // SKYRAMP_UI_USERNAME_<KEY> / SKYRAMP_UI_PASSWORD_<KEY> — alongside the
+    // unkeyed first-credential pair, and codegen binds each generated test to
+    // the pair it was recorded with (SKYR-4110). Dropping a keyed pair here
+    // would fail that test's guard even though the run provided the credential.
+    //
     // Forwarded on presence, not truthiness: the generated guard deliberately
     // distinguishes an unset variable (a misconfiguration, fails fast) from one
     // set to "" (valid on forms that accept a blank password). A truthy check —
     // as used for the URL vars above — would drop the empty case and collapse it
     // into the failure case.
-    //
-    // TODO(SKYR-4110): only ONE credential pair is forwarded, because testbot
-    // exports only the first credential from its `uiCredentials` input. That input
-    // was designed to carry several, so the agent can pick per test case by
-    // authorization role — so a multi-role suite can get a credential its test did
-    // not expect, surfacing as a false 403. The fix is a keyed form
-    // (SKYRAMP_UI_PASSWORD_<KEY>), which needs no new forwarding logic here: the
-    // loop above already forwards SKYRAMP_TEST_SERVICE_URL_* by prefix, so the
-    // same approach applies. Keep the presence-not-truthiness rule when it lands.
-    for (const key of ["SKYRAMP_UI_USERNAME", "SKYRAMP_UI_PASSWORD"]) {
-        const val = hostEnv[key];
-        if (val !== undefined) {
+    for (const [key, val] of Object.entries(hostEnv)) {
+        const isCredential = key === "SKYRAMP_UI_USERNAME" ||
+            key === "SKYRAMP_UI_PASSWORD" ||
+            key.startsWith("SKYRAMP_UI_USERNAME_") ||
+            key.startsWith("SKYRAMP_UI_PASSWORD_");
+        if (isCredential && val !== undefined) {
             env.push(`${key}=${val}`);
         }
     }