@skyramp/mcp 0.3.4 → 0.3.6-rc.1

package/build/tools/test-management/analyzeChangesTool.d.ts

@@ -4,6 +4,7 @@ import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import { CandidateUiPage } from "../../utils/uiPageEnumerator.js";
 import type { FrontendFileIntegration } from "../../types/FrontendIntegration.js";
 import { TraceFile } from "../../types/RepositoryAnalysis.js";
+import { BranchDiffData } from "../../utils/branchDiff.js";
 import { ScannedEndpoint } from "../../utils/repoScanner.js";
 import { TraceParseResult } from "../../utils/trace-parser.js";
 /** Exported for testing: maps a parsed trace result to a TraceFile. */
@@ -25,7 +26,7 @@ export declare const analyzeChangesInputSchema: {
     includeUncommitted: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
 };
 export declare const NO_UI_INSTRUCTIONS = "No UI changes detected \u2014 no blueprint capture needed.";
-export declare const NO_RESOLVABLE_URLS_INSTRUCTIONS = "Frontend changes detected but no candidate URLs could be resolved (workspace baseUrl missing or no router files matched). UI recommendations will be source-grounded only.";
+export declare const NO_RESOLVABLE_URLS_INSTRUCTIONS = "Frontend changes detected but no candidate URLs could be resolved (no route files matched the changed files or their importers, and no frontend baseUrl to fall back to). UI recommendations will be source-grounded only.";
 export declare function buildCaptureInstructions(pages: CandidateUiPage[]): string;
 /**
  * Instruction block for changed frontend files the server determined have no
@@ -45,4 +46,26 @@ export declare function buildAnalyzeChangesResult(parts: {
     outputText: string;
     recommendationPrompt: string;
 }): CallToolResult;
+/**
+ * Coverage is discovered from the working tree, so a test file the PR itself adds looks
+ * identical to pre-existing coverage. This is what the budgeter reads to decide whether
+ * an empty plan is a dedup artifact or the author's own coverage.
+ *
+ * No diff means no answer, so it reports `true` and the reserve stays shut. `diffData` is
+ * absent in full-repo scope — where fullRepoCatalog deliberately drops externally covered
+ * scenarios, and promoting them back would contradict the prompt the agent reads — and
+ * after a branch-diff failure, where nothing is known about the changed files at all.
+ *
+ * Classification comes from discovery, not from `isTestFile`: the flag has to agree with
+ * whatever built the coverage keys it guards.
+ *
+ * `userChangedFiles` is the bot-filtered list. The bot commits its generated tests onto
+ * the branch it analyzed, and those filenames are exactly what the discovery patterns
+ * exist to match — so reading the raw base..HEAD list shut the reserve on every re-run
+ * of a branch: run 1 generates the tests, run 2 sees them. When the filter cannot answer
+ * (no bot commit yet, or a git failure) the raw list stands. That is safe in the same
+ * direction as the `!diffData` case: the raw list can only hold MORE files, so the
+ * fallback shuts the reserve rather than opening it.
+ */
+export declare function computeDiffChangesTestFiles(diffData: BranchDiffData | undefined, userChangedFiles?: string[] | null): boolean;
 export declare function registerAnalyzeChangesTool(server: McpServer): void;

package/build/tools/test-management/analyzeChangesTool.js

@@ -10,17 +10,20 @@ import { dualChannelResult } from "../../utils/utils.js";
 import { parseWorkspaceAuthType, getDefaultAuthHeader, WorkspaceAuthType, readWorkspaceConfigRaw } from "../../utils/workspaceAuth.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { makeProgressReporter } from "../../utils/progress.js";
-import { StateManager, registerSession, storeSessionData, setTestsRepoDir, getActiveRunStatePath, setActiveRunStatePath, } from "../../utils/AnalysisStateManager.js";
+import { StateManager, registerSession, storeSessionData, rememberTestsRepoDir, getActiveRunStatePath, setActiveRunStatePath, } from "../../utils/AnalysisStateManager.js";
 import { buildRecommendationPrompt, computeScoredCandidates } from "../../prompts/test-recommendation/test-recommendation-prompt.js";
 import { hasFlutterSdkDep, isFrontendFile, isTestFile } from "../../prompts/test-recommendation/scopeAssessment.js";
 import { buildExternalCoverageSet } from "../../prompts/test-recommendation/recommendationShared.js";
+import { resolveSubjectEndpoints } from "../../utils/subjectEndpoints.js";
+import { collectChangedRouteLines } from "../../utils/changedRoutes.js";
 import { CandidateSource, computeCandidateId } from "../../types/Recommendation.js";
 import { selectPlan } from "../../recommendation/planRanker.js";
 import { buildApprovedPlanItem } from "../../utils/planMatchKeys.js";
-import { enumerateCandidateUiPages } from "../../utils/uiPageEnumerator.js";
+import { enumerateCandidateUiPages, MAX_CANDIDATE_PAGES } from "../../utils/uiPageEnumerator.js";
 import { checkFrontendFileIntegration } from "../../utils/frontendIntegration.js";
 import { MAX_RECOMMENDATIONS, MAX_TESTS_TO_GENERATE } from "../../prompts/test-recommendation/recommendationSections.js";
 import { TestDiscoveryService } from "../../services/TestDiscoveryService.js";
+import { isDiscoveredTestFile } from "../../utils/testFileClassification.js";
 import { ScenarioSource, AnalysisScope } from "../../types/RepositoryAnalysis.js";
 import { computeBranchDiff } from "../../utils/branchDiff.js";
 import { classifyEndpointsByChangedFiles, selectRemovalCandidateFiles, recoverRemovedEndpointsFromBase, } from "../../utils/routeParsers.js";
@@ -324,23 +327,35 @@ export const analyzeChangesInputSchema = {
 // for UI recommendation reasoning (enforced at submit time by the Blueprint
 // Citation Invariant in the testbot prompt).
 export const NO_UI_INSTRUCTIONS = `No UI changes detected — no blueprint capture needed.`;
-export const NO_RESOLVABLE_URLS_INSTRUCTIONS = `Frontend changes detected but no candidate URLs could be resolved (workspace baseUrl missing or no router files matched). UI recommendations will be source-grounded only.`;
+export const NO_RESOLVABLE_URLS_INSTRUCTIONS = `Frontend changes detected but no candidate URLs could be resolved (no route files matched the changed files or their importers, and no frontend baseUrl to fall back to). UI recommendations will be source-grounded only.`;
 export function buildCaptureInstructions(pages) {
+    const pathOnly = pages.some((p) => p.baseUrlResolved === false);
     const pagesYaml = pages
-        .map((p, i) => `  ${i + 1}. ${p.url}  (sourcedFrom: ${p.sourcedFrom.join(", ") || "(none)"}, strategy: ${p.strategy})`)
+        .map((p, i) => `  ${i + 1}. ${p.url}  (sourcedFrom: ${p.sourcedFrom.join(", ") || "(none)"}${p.via ? `, via: ${p.via.join(", ")}` : ""}, strategy: ${p.strategy})`)
         .join("\n");
+    const capNote = pages.length >= MAX_CANDIDATE_PAGES
+        ? `\n(The list is capped at ${MAX_CANDIDATE_PAGES} pages — direct route matches first, then the pages that render the most changed files.)`
+        : "";
+    // The server could not resolve a frontend baseUrl (no frontend service with
+    // `api.baseUrl`, no SKYRAMP_TEST_BASE_URL). The paths are still exact; the
+    // agent supplies the host.
+    const baseUrlStep = pathOnly
+        ? `
+**The entries above are URL paths, not full URLs** — the workspace declares no frontend service with \`api.baseUrl\`. Determine the frontend base URL once before capturing — the testbot workflow's \`targetReadyCheckCommand\` or the dev-server port in \`package.json\` scripts usually names it — then prefix every path with it. Log an \`issuesFound\` info entry recommending that \`api.baseUrl\` be set on the frontend service in \`.skyramp/workspace.yml\`.
+`
+        : "";
     return `Frontend changes detected. **Before writing any UI recommendation \`reasoning\`, capture blueprints on the candidate UI pages below.** Those captures stay in your tool-result history and serve as element vocabulary — the recommendation catalog further down gives you the authoring rules; you bring the observed elements.
 
-**Candidate URLs:**
-${pagesYaml}
-
+**Candidate ${pathOnly ? "URL paths" : "URLs"}:**
+${pagesYaml}${capNote}
+${baseUrlStep}
 **For each candidate URL:**
   - \`browser_navigate\` to the URL
   - \`browser_blueprint\` to capture the page
 
 You don't need to thread the blueprints back into a tool call — they're in your context once captured.
 
-If a candidate URL 404s or redirects unexpectedly, navigate from the workspace baseUrl and explore (admin apps mount routes under base prefixes the source extraction can't see). If the page rendered but lacks the changed feature (gated UI: modal, dropdown, accordion), do NOT iterate further during this step — UI recs will fall back to source-grounded prose for those, and the agent's later trace recording (Task 2) will navigate into the gate via capture-act-capture.
+If a candidate URL 404s or redirects unexpectedly, navigate from the frontend base URL and explore (admin apps mount routes under base prefixes the source extraction can't see). If the page rendered but lacks the changed feature (gated UI: modal, dropdown, accordion), do NOT iterate further during this step — UI recs will fall back to source-grounded prose for those, and the agent's later trace recording (Task 2) will navigate into the gate via capture-act-capture.
 
 If \`browser_blueprint\` fails on every candidate URL (app unreachable, all 404s), proceed and log an \`issuesFound\` info entry. Recommendations will be source-grounded; non-UI work is unaffected.`;
 }
@@ -376,6 +391,32 @@ export function buildAnalyzeChangesResult(parts) {
     const executionPlan = `\`\`\`json\n${parts.structuredSummary}\n\`\`\`\n\n## UI Blueprint Capture — do this BEFORE writing UI recommendation reasoning\n${parts.uiInstructions}\n\n${parts.outputText}\n\n---\n\n## Pre-built Test Catalog — Fill in placeholders from source code, then display verbatim\n⚠️ Do NOT reformat, rename sections, or generate a new catalog. Replace \`<…from source>\` values, then show this output exactly as-is, grouped by test type.\n\n${parts.recommendationPrompt}`;
     return dualChannelResult({ executionPlan });
 }
+/**
+ * Coverage is discovered from the working tree, so a test file the PR itself adds looks
+ * identical to pre-existing coverage. This is what the budgeter reads to decide whether
+ * an empty plan is a dedup artifact or the author's own coverage.
+ *
+ * No diff means no answer, so it reports `true` and the reserve stays shut. `diffData` is
+ * absent in full-repo scope — where fullRepoCatalog deliberately drops externally covered
+ * scenarios, and promoting them back would contradict the prompt the agent reads — and
+ * after a branch-diff failure, where nothing is known about the changed files at all.
+ *
+ * Classification comes from discovery, not from `isTestFile`: the flag has to agree with
+ * whatever built the coverage keys it guards.
+ *
+ * `userChangedFiles` is the bot-filtered list. The bot commits its generated tests onto
+ * the branch it analyzed, and those filenames are exactly what the discovery patterns
+ * exist to match — so reading the raw base..HEAD list shut the reserve on every re-run
+ * of a branch: run 1 generates the tests, run 2 sees them. When the filter cannot answer
+ * (no bot commit yet, or a git failure) the raw list stands. That is safe in the same
+ * direction as the `!diffData` case: the raw list can only hold MORE files, so the
+ * fallback shuts the reserve rather than opening it.
+ */
+export function computeDiffChangesTestFiles(diffData, userChangedFiles) {
+    if (!diffData)
+        return true;
+    return (userChangedFiles ?? diffData.changedFiles).some(isDiscoveredTestFile);
+}
 export function registerAnalyzeChangesTool(server) {
     server.registerTool(TOOL_NAME, {
         annotations: {
@@ -736,7 +777,9 @@ export function registerAnalyzeChangesTool(server) {
             let discoveredRelevantExternalPaths = [];
             try {
                 const testDiscoveryService = new TestDiscoveryService();
-                setTestsRepoDir(params.testsRepoDir);
+                // Run-scoped: only the primary call carries testsRepoDir, so never
+                // let a related repo's call clear it (SKYR-4204).
+                rememberTestsRepoDir(params.testsRepoDir);
                 const discoveryResult = await testDiscoveryService.discoverTests(testDir ?? params.repositoryPath, { changedResources, changedSymbols, preciseResources: (changedSymbols?.length ?? 0) > 0, changedFrontendFiles, changedSelectors });
                 existingTests = discoveryResult.tests.map((test) => ({
                     testFile: test.testFile,
@@ -1321,19 +1364,21 @@ export function registerAnalyzeChangesTool(server) {
             // same classification without re-deriving it. Absent on backend-only PRs.
             //
             // candidateUiPages is enumerated programmatically via the strategy
-            // ladder in uiPageEnumerator (framework route grep, source-grounded
-            // routes, root fallback). The agent uses these to capture
+            // ladder in uiPageEnumerator (framework route grep + import graph,
+            // source-grounded routes, root fallback). The agent uses these to capture
             // browser_blueprints — see uiInstructions below, which this tool returns
             // so the agent captures element vocabulary for UI rec reasoning.
             const uiContext = await (async () => {
                 // changedFrontendFiles computed above (before discoverTests) — reuse here.
                 if (changedFrontendFiles.length === 0)
                     return undefined;
-                const candidateUiPages = await enumerateCandidateUiPages(params.repositoryPath, changedFrontendFiles);
                 // SKYR-3855: deterministic production-importer check, computed here so
                 // downstream consumers (testbot prompt) can skip UI generation for
                 // unintegrated components on a server fact instead of a mid-run grep.
+                // Computed first: the enumerator resolves changed non-route files to
+                // the pages that import them.
                 const frontendFileIntegration = checkFrontendFileIntegration(params.repositoryPath, changedFrontendFiles);
+                const candidateUiPages = await enumerateCandidateUiPages(params.repositoryPath, changedFrontendFiles, frontendFileIntegration);
                 return {
                     changedFrontendFiles,
                     candidateUiPages,
@@ -1370,13 +1415,29 @@ export function registerAnalyzeChangesTool(server) {
             // computeScoredCandidates is the single source of truth for both.
             const topN = params.topN ?? MAX_RECOMMENDATIONS;
             const scoredResult = computeScoredCandidates(fullAnalysis, analysisScope, topN, params.maxGenerate);
+            // Resolve each scenario's subject endpoints once, here — this is the only
+            // point that has the scenarios, the diff, and runs before BOTH consumers
+            // (selectPlan below, and the two prompt renderers). `scored.scenario` is
+            // the SAME object as the entry in `allDraftedScenarios` (assigned by
+            // reference into businessContext.draftedScenarios, then into
+            // repositoryAnalysis.scenarios below), so this mutation also fills what
+            // gets persisted. Filling later would leave one consumer keying off a
+            // different subject (SKYR-4214).
+            const changedRoutesForSubjects = collectChangedRouteLines(diffText ?? "");
+            for (const scored of scoredResult.scored) {
+                scored.scenario.subjectEndpoints = resolveSubjectEndpoints(scored.scenario, {
+                    changedRoutes: changedRoutesForSubjects,
+                });
+            }
             const externalCoverage = buildExternalCoverageSet(testLocationsByType);
+            const diffChangesTestFiles = computeDiffChangesTestFiles(diffData, await getUserChangedFiles(params.repositoryPath));
             const planBudgetContext = {
                 maxGenerate: scoredResult.maxGen,
                 maxTotal: topN,
                 isUIOnlyPR: scoredResult.isUIOnlyPR,
                 hasFrontendChanges: scoredResult.hasFrontendChanges,
                 externalCoverageKeys: [...externalCoverage],
+                diffChangesTestFiles,
             };
             let approvedPlan;
             if (scoredResult.scored.length > 0) {
@@ -1386,6 +1447,7 @@ export function registerAnalyzeChangesTool(server) {
                     isUIOnlyPR: planBudgetContext.isUIOnlyPR,
                     hasFrontendChanges: planBudgetContext.hasFrontendChanges,
                     externalCoverage,
+                    diffChangesTestFiles,
                 };
                 const serverCandidates = scoredResult.scored.map(({ scenario, priority, novelty }) => ({
                     scenario,
@@ -1401,6 +1463,7 @@ export function registerAnalyzeChangesTool(server) {
                     generate: plan.generate.map(buildApprovedPlanItem),
                     additional: plan.additional.map(buildApprovedPlanItem),
                     demotions: [],
+                    dropped: plan.dropped,
                 };
             }
             const unifiedState = {

package/build/tools/test-management/analyzeTestHealthTool.js

@@ -175,13 +175,13 @@ export function registerAnalyzeTestHealthTool(server) {
             // every repo in a multi-repo run (endpoints in Repo A, tests in Repo B).
             // TODO(multi-repo): existingTests is scoped to the current repo only — related
             // repo tests are not pre-loaded, discoverable only via the grep instruction.
-            // Skip the async lookups when there are no tests — symbol discovery is a no-op.
-            let allRepoPaths = [repositoryPath];
-            if (existingTests.length > 0) {
-                const relatedRepoKeys = await stateManager.listRelatedRepos();
-                const relatedRepoPaths = (await Promise.all(relatedRepoKeys.map(r => stateManager.getRepoRepositoryPath(r)))).filter((p) => typeof p === "string");
-                allRepoPaths = [repositoryPath, ...relatedRepoPaths];
-            }
+            // Every root in the RUN, not the requested repo plus the related ones: on a
+            // related-repo call the latter omits the primary and repeats the requested
+            // repo (SKYR-4246). Dedupe by root because a legacy untagged primary can also
+            // appear as a related section holding the same path.
+            const allRepoPaths = [
+                ...new Set((await stateManager.listRepoCheckouts()).map(c => c.root)),
+            ];
             const promptText = buildDriftAnalysisPrompt(stateManager.getStatePath(), apiTests.map((t) => ({ testFile: t.testFile, source: t.source })), uiDriftParams, allRepoPaths, stateData?.externalTestResults);
             return {
                 structuredContent: { prompt: promptText },

package/build/tools/test-management/registerTestPlanTool.d.ts

@@ -1,2 +1,205 @@
+import { z } from "zod";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { HttpMethod, TestType } from "../../types/TestTypes.js";
+import { Candidate, DiscriminatorKind } from "../../types/Recommendation.js";
+import { ChangedRoute } from "../../utils/changedRoutes.js";
+declare const registerCandidateSchema: z.ZodObject<{
+    scenarioName: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodEnum<["new_endpoint", "bug_caught", "business_rule", "security_boundary", "data_integrity", "breaking_change", "auth", "error_handling", "workflow", "data_validation", "crud"]>;
+    priority: z.ZodEnum<["high", "medium", "low"]>;
+    testType: z.ZodEffects<z.ZodNativeEnum<typeof TestType>, TestType, TestType>;
+    steps: z.ZodArray<z.ZodObject<{
+        order: z.ZodNumber;
+        method: z.ZodNativeEnum<typeof HttpMethod>;
+        path: z.ZodString;
+        description: z.ZodString;
+        interactionType: z.ZodEnum<["success", "error", "edge-case"]>;
+        requestBody: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        queryParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+        responseBody: z.ZodOptional<z.ZodUnion<[z.ZodRecord<z.ZodString, z.ZodAny>, z.ZodArray<z.ZodAny, "many">]>>;
+        expectedStatusCode: z.ZodNumber;
+        expectedResponseFields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        bodyMustInclude: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        chainsFrom: z.ZodOptional<z.ZodUnion<[z.ZodObject<{
+            sourceStep: z.ZodNumber;
+            sourceField: z.ZodString;
+            sourceLocation: z.ZodEnum<["body", "header", "cookie"]>;
+            targetParam: z.ZodString;
+            targetLocation: z.ZodEnum<["path", "body", "query", "header", "cookie"]>;
+        }, "strip", z.ZodTypeAny, {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }, {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }>, z.ZodArray<z.ZodObject<{
+            sourceStep: z.ZodNumber;
+            sourceField: z.ZodString;
+            sourceLocation: z.ZodEnum<["body", "header", "cookie"]>;
+            targetParam: z.ZodString;
+            targetLocation: z.ZodEnum<["path", "body", "query", "header", "cookie"]>;
+        }, "strip", z.ZodTypeAny, {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }, {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }>, "many">]>>;
+    }, "strip", z.ZodTypeAny, {
+        path: string;
+        method: HttpMethod;
+        description: string;
+        order: number;
+        interactionType: "error" | "success" | "edge-case";
+        expectedStatusCode: number;
+        queryParams?: Record<string, any> | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: any[] | Record<string, any> | undefined;
+        expectedResponseFields?: string[] | undefined;
+        chainsFrom?: {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        } | {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }[] | undefined;
+        bodyMustInclude?: string[] | undefined;
+    }, {
+        path: string;
+        method: HttpMethod;
+        description: string;
+        order: number;
+        interactionType: "error" | "success" | "edge-case";
+        expectedStatusCode: number;
+        queryParams?: Record<string, any> | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: any[] | Record<string, any> | undefined;
+        expectedResponseFields?: string[] | undefined;
+        chainsFrom?: {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        } | {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }[] | undefined;
+        bodyMustInclude?: string[] | undefined;
+    }>, "many">;
+    discriminator: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodNativeEnum<typeof DiscriminatorKind>;
+        changedCodeAnchor: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        kind: DiscriminatorKind;
+        changedCodeAnchor: string;
+    }, {
+        kind: DiscriminatorKind;
+        changedCodeAnchor: string;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    description: string;
+    priority: "high" | "medium" | "low";
+    testType: TestType;
+    scenarioName: string;
+    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    steps: {
+        path: string;
+        method: HttpMethod;
+        description: string;
+        order: number;
+        interactionType: "error" | "success" | "edge-case";
+        expectedStatusCode: number;
+        queryParams?: Record<string, any> | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: any[] | Record<string, any> | undefined;
+        expectedResponseFields?: string[] | undefined;
+        chainsFrom?: {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        } | {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }[] | undefined;
+        bodyMustInclude?: string[] | undefined;
+    }[];
+    discriminator?: {
+        kind: DiscriminatorKind;
+        changedCodeAnchor: string;
+    } | undefined;
+}, {
+    description: string;
+    priority: "high" | "medium" | "low";
+    testType: TestType;
+    scenarioName: string;
+    category: "new_endpoint" | "bug_caught" | "business_rule" | "security_boundary" | "data_integrity" | "breaking_change" | "auth" | "error_handling" | "workflow" | "data_validation" | "crud";
+    steps: {
+        path: string;
+        method: HttpMethod;
+        description: string;
+        order: number;
+        interactionType: "error" | "success" | "edge-case";
+        expectedStatusCode: number;
+        queryParams?: Record<string, any> | undefined;
+        requestBody?: Record<string, any> | undefined;
+        responseBody?: any[] | Record<string, any> | undefined;
+        expectedResponseFields?: string[] | undefined;
+        chainsFrom?: {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        } | {
+            sourceStep: number;
+            sourceField: string;
+            sourceLocation: "body" | "header" | "cookie";
+            targetParam: string;
+            targetLocation: "path" | "body" | "header" | "cookie" | "query";
+        }[] | undefined;
+        bodyMustInclude?: string[] | undefined;
+    }[];
+    discriminator?: {
+        kind: DiscriminatorKind;
+        changedCodeAnchor: string;
+    } | undefined;
+}>;
+type RegisterCandidateInput = z.infer<typeof registerCandidateSchema>;
+/** Build the agent-submitted candidates. Discriminator claims are verified
+ *  later, by {@link applyDiscriminatorClaims}, once the merge has settled which
+ *  scenario each name resolves to. Exported for the direct unit test in
+ *  registerTestPlanTool.test.ts — a candidate that does not survive selection
+ *  never reaches the persisted plan, so its subjectEndpoints fill is not
+ *  observable through the tool's output, and testing here avoids coupling the
+ *  fill to what selection happens to keep. */
+export declare function buildAgentCandidates(candidates: RegisterCandidateInput[], changedRoutes: ChangedRoute[]): Candidate[];
 export declare function registerRegisterTestPlanTool(server: McpServer): void;
+export {};