diff --git a/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs b/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs index f9d5dcc5328..d58328ab3ac 100644 --- a/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs +++ b/dotnet/src/Microsoft.Agents.AI.Mcp/Skills/Loaders/AgentMcpSkillArchiveExtractor.cs @@ -17,6 +17,7 @@ namespace Microsoft.Agents.AI; /// Supports ZIP payloads. Extraction is guarded against path-traversal ("zip-slip") attacks and /// bounded by a maximum file count and total uncompressed size to mitigate decompression-bomb attacks. /// Later entries resolving to an existing file are skipped, preserving the first file's content. +/// Archives containing file names that differ only by case are rejected. /// internal static partial class AgentMcpSkillArchiveExtractor { @@ -83,7 +84,7 @@ internal static ArchiveFormat DetectFormat(byte[] bytes, string? mediaType, stri /// The maximum total uncompressed size, in bytes, of all extracted files. /// An optional logger reporting each skipped colliding archive member. /// The format is not . - /// The archive exceeds one of the supplied limits. + /// The archive exceeds one of the supplied limits or contains file names that differ only by case. internal static void Extract( byte[] bytes, ArchiveFormat format, @@ -113,7 +114,7 @@ private static void ExtractZip(Stream source, string fullTarget, int maxFileCoun long remainingBytes = maxUncompressedSizeBytes; int fileCount = 0; - var destinations = new HashSet(OperatingSystem.IsWindows() ? StringComparer.OrdinalIgnoreCase : StringComparer.Ordinal); + var destinations = new Dictionary(StringComparer.OrdinalIgnoreCase); string skillName = SanitizePathForLog(Path.GetFileName(fullTarget)); foreach (ZipArchiveEntry entry in archive.Entries) @@ -136,12 +137,19 @@ private static void ExtractZip(Stream source, string fullTarget, int maxFileCoun } // Normalization can map distinct archive names to one path; keep the first file. - if (!destinations.Add(destination)) + if (destinations.TryGetValue(destination, out string? previous)) { + if (!string.Equals(previous, destination, StringComparison.Ordinal)) + { + throw new InvalidDataException("Skill archive contains file names that differ only by case."); + } + LogArchiveMemberCollision(logger, skillName, SanitizePathForLog(entry.FullName)); continue; } + destinations.Add(destination, destination); + Directory.CreateDirectory(Path.GetDirectoryName(destination)!); // CreateNew also prevents overwrites through filesystem aliases, such as trailing dots on Windows. diff --git a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs index 5484348c59e..34a91b34b90 100644 --- a/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs +++ b/dotnet/src/Microsoft.Agents.AI/Skills/File/AgentFileSkillsSource.cs @@ -27,6 +27,9 @@ namespace Microsoft.Agents.AI; /// value is retained for duplicate keys, and subsequent entries produce warnings without rejecting the skill. /// Resource and script files are discovered by scanning the skill /// directory for files with matching extensions. Invalid resources are skipped with logged warnings. +/// Skills whose resource names or script names differ only by case are skipped. +/// Names are compared using ; Unicode equivalence +/// follows the target runtime. /// Resource and script paths are checked against path traversal and symlink escape attacks. /// Discovered files are revalidated against their trusted skill directory immediately before use. /// @@ -223,6 +226,12 @@ private void SearchDirectoriesForSkills(string directory, string trustedRootFull var resources = this.DiscoverResourceFiles(scope, frontmatter.Name); var scripts = this.DiscoverScriptFiles(scope, frontmatter.Name); + if (this.HasCaseVariantNames(frontmatter.Name, "resource", resources.Select(r => r.Name)) || + this.HasCaseVariantNames(frontmatter.Name, "script", scripts.Select(s => s.Name))) + { + return null; + } + return new AgentFileSkill( frontmatter: frontmatter, content: content, @@ -231,6 +240,31 @@ private void SearchDirectoriesForSkills(string directory, string trustedRootFull scripts: scripts); } + /// + /// Checks for collisions among the supplied names using + /// and logs the first collision. + /// + /// The owning skill's name, used only in the log message, not in comparisons. + /// The entry category ("resource" or "script"), used only in the log message. + /// The resource or script names to compare with each other. + /// if a collision is found; otherwise, . + private bool HasCaseVariantNames(string skillName, string kind, IEnumerable entryNames) + { + var seen = new Dictionary(StringComparer.OrdinalIgnoreCase); + foreach (string name in entryNames) + { + if (seen.TryGetValue(name, out string? previous)) + { + LogCaseVariantNames(this._logger, skillName, kind, SanitizePathForLog(previous), SanitizePathForLog(name)); + return true; + } + + seen.Add(name, name); + } + + return false; + } + private bool TryParseFrontmatter(string content, string skillFilePath, [NotNullWhen(true)] out AgentSkillFrontmatter? frontmatter) { frontmatter = null; @@ -785,6 +819,9 @@ private static void ValidateExtensions(IEnumerable? extensions) [LoggerMessage(LogLevel.Error, "SKILL.md at '{SkillFilePath}': skill name '{SkillName}' does not match parent directory name '{DirectoryName}'")] private static partial void LogNameDirectoryMismatch(ILogger logger, string skillFilePath, string skillName, string directoryName); + [LoggerMessage(LogLevel.Error, "Skipping skill '{SkillName}': {Kind} names '{FirstName}' and '{SecondName}' differ only by case")] + private static partial void LogCaseVariantNames(ILogger logger, string skillName, string kind, string firstName, string secondName); + [LoggerMessage(LogLevel.Warning, "Skipping resource in skill '{SkillName}': '{ResourcePath}' references a path outside the skill directory")] private static partial void LogResourcePathTraversal(ILogger logger, string skillName, string resourcePath); diff --git a/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs b/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs index 6a4ed11b222..fe3db8cb764 100644 --- a/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs +++ b/dotnet/tests/Microsoft.Agents.AI.Mcp.UnitTests/Skills/AgentMcpSkillsSourceArchiveTests.cs @@ -259,7 +259,6 @@ public static TheoryData ArchiveCollisionCases }; if (OperatingSystem.IsWindows()) { - aliases.Add("refs/POLICY.md"); aliases.Add("refs/policy.md."); } @@ -312,8 +311,7 @@ public async Task GetSkillsAsync_CollidingArchiveResources_KeepsFirstFileAndLogs for (int i = 0; i < 2; i++) { var skill = Assert.Single(await source.GetSkillsAsync(TestAgentSkillsSourceContextFactory.Create())); - string resourceName = aliasFirst && alias == "refs/POLICY.md" ? alias : "refs/policy.md"; - var resource = await skill.GetResourceAsync(resourceName); + var resource = await skill.GetResourceAsync("refs/policy.md"); Assert.NotNull(resource); Assert.Equal("First resource.", await resource.ReadAsync()); var other = await skill.GetResourceAsync("refs/other.md"); @@ -334,6 +332,46 @@ public async Task GetSkillsAsync_CollidingArchiveResources_KeepsFirstFileAndLogs Times.Exactly(2)); } + [Theory] + [InlineData("refs/policy.md", "refs/POLICY.md", false)] + [InlineData("refs/policy.md", "refs/POLICY.md", true)] + [InlineData("refs/policy.md", "REFS/policy.md", false)] + [InlineData("refs/policy.md", "REFS/policy.md", true)] + [InlineData("scripts/run.py", "scripts/RUN.py", false)] + [InlineData("scripts/run.py", "scripts/RUN.py", true)] + [InlineData("SKILL.md", "skill.md", false)] + [InlineData("SKILL.md", "skill.md", true)] + public async Task GetSkillsAsync_CaseVariantArchiveNames_SkipsSkillAsync(string name, string variant, bool variantFirst) + { + // Arrange + var files = new List<(string Path, string Content)> + { + (variantFirst ? variant : name, ArchivedSkillMd), + (variantFirst ? name : variant, ArchivedSkillMd), + }; + if (!string.Equals(name, "SKILL.md", StringComparison.Ordinal)) + { + files.Add(("SKILL.md", ArchivedSkillMd)); + } + + byte[] archive = BuildZip(files.ToArray()); + await using var server = CreateArchiveServer( + ArchiveIndex("archived-skill", "skill://archives/archived-skill.zip"), + new Dictionary { ["archived-skill"] = archive }); + await using var client = await server.CreateClientAsync(); + var source = new AgentMcpSkillsSource(client, new() { ArchiveSkillsDirectory = this._extractionRoot }); + + for (int i = 0; i < 2; i++) + { + // Act + var skills = await source.GetSkillsAsync(TestAgentSkillsSourceContextFactory.Create()); + + // Assert + Assert.Empty(skills); + Assert.False(Directory.Exists(Path.Combine(this._extractionRoot, "archived-skill"))); + } + } + [Theory] [InlineData("SKILL.md", false)] [InlineData("SKILL.md", true)] diff --git a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs index 1599023e1b7..3603498d9a2 100644 --- a/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs +++ b/dotnet/tests/Microsoft.Agents.AI.UnitTests/AgentSkills/FileAgentSkillLoaderTests.cs @@ -2151,6 +2151,41 @@ public async Task GetSkillsAsync_DeepResource_DiscoveredWithHigherDepthAsync() Assert.Equal("f1/f2/f3/data.json", skill.GetTestResources()![0].Name); } + [Theory] + [InlineData("test.md", "TEST.md")] + [InlineData("refs/test.md", "REFS/test.md")] + [InlineData("scripts/run.py", "scripts/RUN.py")] + [InlineData("\u00e9.md", "\u00c9.md")] + [InlineData("scripts/\u00e9.py", "scripts/\u00c9.py")] +#if NET10_0_OR_GREATER + [InlineData("\u03a3.md", "\u03c2.md")] + [InlineData("scripts/\u03a3.py", "scripts/\u03c2.py")] +#endif + public async Task GetSkillsAsync_NamesDifferOnlyByCase_SkipsSkillAsync(string firstName, string secondName) + { + // Arrange + string skillDir = this.CreateSkillDirectory("case-skill", "A skill", "Body."); + string firstPath = Path.Combine(skillDir, firstName); + string secondPath = Path.Combine(skillDir, secondName); + Directory.CreateDirectory(Path.GetDirectoryName(firstPath)!); + Directory.CreateDirectory(Path.GetDirectoryName(secondPath)!); + File.WriteAllText(firstPath, "first"); + File.WriteAllText(secondPath, "second"); + if (Directory.EnumerateFiles(skillDir, "*", SearchOption.AllDirectories).Count() != 3) + { + Assert.Skip("The filesystem is not case-sensitive."); + } + + this.CreateSkillDirectory("other-skill", "A skill", "Body."); + var source = new AgentFileSkillsSource(this._testRoot, s_noOpExecutor); + + // Act + var skills = await source.GetSkillsAsync(TestAgentSkillsSourceContextFactory.Create()); + + // Assert + Assert.Equal("other-skill", Assert.Single(skills).Frontmatter.Name); + } + private string CreateSkillDirectory(string name, string description, string body) { string skillDir = Path.Combine(this._testRoot, name); diff --git a/python/packages/core/agent_framework/_skills.py b/python/packages/core/agent_framework/_skills.py index 464d79ac7e2..4fd42e7ddf5 100644 --- a/python/packages/core/agent_framework/_skills.py +++ b/python/packages/core/agent_framework/_skills.py @@ -1851,6 +1851,11 @@ async def get_script(self, name: str) -> SkillScript | None: class FileSkill(Skill): """A :class:`Skill` discovered from a filesystem directory backed by a SKILL.md file. + Resource and script lookup is case-insensitive, so two resources or two + scripts whose names differ only by case (e.g. ``readme.md`` and + ``README.md``) are ambiguous and rejected with :class:`ValueError`. + Comparison uses :meth:`str.lower`, not :meth:`str.casefold`. + Attributes: path: Absolute path to the directory containing this skill. """ @@ -1874,6 +1879,9 @@ def __init__( path: Absolute path to the skill directory on disk. resources: Resources discovered for this skill. scripts: Scripts discovered for this skill. + + Raises: + ValueError: If resource or script names differ only by case. """ self._frontmatter = frontmatter @@ -1881,6 +1889,8 @@ def __init__( self.path = path self._resources: list[SkillResource] = list(resources) if resources is not None else [] self._scripts: list[SkillScript] = list(scripts) if scripts is not None else [] + self._reject_case_variant_names(frontmatter.name, "resource", self._resources) + self._reject_case_variant_names(frontmatter.name, "script", self._scripts) self._cached_content: str | None = None @property @@ -1938,6 +1948,21 @@ async def get_script(self, name: str) -> SkillScript | None: name_lower = name.lower() return next((s for s in self._scripts if s.name.lower() == name_lower), None) + @staticmethod + def _reject_case_variant_names(skill_name: str, kind: str, entries: Sequence[SkillResource | SkillScript]) -> None: + """Reject names with equal ``str.lower()`` keys, matching resource and script lookup. + + Raises: + ValueError: If two names differ only by case. + """ + names: dict[str, str] = {} + for entry in entries: + previous = names.setdefault(entry.name.lower(), entry.name) + if previous != entry.name: + raise ValueError( + f"Skill '{skill_name}' has {kind} names that differ only by case: '{previous}' and '{entry.name}'." + ) + # endregion @@ -3143,6 +3168,9 @@ class FileSkillsSource(SkillsSource): Use *script_filter* and *resource_filter* predicates to control which discovered files are included. + Resource and script names that differ only by case skip the whole skill + with a warning. + Security: file-based metadata is XML-escaped before prompt injection, and resource reads are guarded against path traversal and symlink escape. Only use skills from trusted sources. @@ -3295,13 +3323,17 @@ async def get_skills(self, context: SkillsSourceContext) -> list[Skill]: ) ) - file_skill = FileSkill( - frontmatter=frontmatter, - content=content, - path=skill_path, - resources=resources, - scripts=scripts, - ) + try: + file_skill = FileSkill( + frontmatter=frontmatter, + content=content, + path=skill_path, + resources=resources, + scripts=scripts, + ) + except ValueError as exc: + logger.warning("Skipping skill '%s' at '%s': %s", frontmatter.name, skill_path, exc) + continue skills[file_skill.frontmatter.name] = file_skill logger.info("Loaded skill: %s", file_skill.frontmatter.name) @@ -5029,8 +5061,7 @@ def _extract_archive_to_memory( ``..`` parent-traversal ("zip-slip") aborts extraction of the whole archive by raising. Extraction is bounded by a maximum file count and total uncompressed size to mitigate decompression-bomb attacks. No filesystem is touched. - Later members whose normalized paths match case-insensitively are skipped - with a warning; the first member's spelling and content are retained. + Duplicate normalized member paths reject the archive. Args: data: The raw archive bytes. @@ -5043,7 +5074,7 @@ def _extract_archive_to_memory( Raises: ValueError: If the format is unknown, a limit is exceeded, or a member attempts - a path-traversal ("zip-slip") escape. + a path-traversal ("zip-slip") escape, or two members normalize to the same path. OSError: If the payload cannot be read. zipfile.BadZipFile: If a ZIP payload is malformed. """ @@ -5061,7 +5092,6 @@ def _extract_zip_to_memory( """Read regular files from a ZIP archive into memory. See :func:`_extract_archive_to_memory`.""" remaining_bytes = max_uncompressed_size_bytes files: dict[str, bytes] = {} - seen_names: set[str] = set() file_count = 0 for info in archive.infolist(): @@ -5075,22 +5105,12 @@ def _extract_zip_to_memory( name = _normalize_archive_member_name(info.filename) if name is None: continue - - # Match FileSkill's case-insensitive lookup; retain the first member's spelling. - lookup_name = name.lower() - if lookup_name in seen_names: - logger.warning( - "Skipping duplicate archive member %r: normalized path %r matches an earlier member; " - "keeping the first file", - info.filename, - name, - ) - continue + if name in files: + raise ValueError(f"Duplicate archive member {info.filename!r}: normalized path {name!r}.") with archive.open(info) as source: content, remaining_bytes = _read_member_with_limit(source, remaining_bytes) files[name] = content - seen_names.add(lookup_name) return files @@ -5110,8 +5130,8 @@ class _ArchiveEntryLoader: Extraction is hardened against path-traversal ("zip-slip") member names, oversized downloads, excessive file counts, and decompression bombs. - Member paths are compared case-insensitively; collisions are skipped with a - warning, keeping the first file's spelling and content. + Duplicate normalized member paths reject the archive, and resource names that + differ only by case reject the skill. Supplied SHA-256 digests are verified before extraction; archives without a digest remain supported. """ @@ -5273,7 +5293,11 @@ def _build_skill(self, entry: _McpSkillIndexEntry, data: bytes, mime_type: str | def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes]) -> FileSkill | None: """Assemble an in-memory :class:`FileSkill` from the archive's extracted files.""" - skill_md_key = self._find_skill_md(files) + try: + skill_md_key = self._find_skill_md(files) + except ValueError as exc: + logger.warning("Skipping skill '%s': %s", entry.name, exc) + return None if skill_md_key is None: logger.warning("Skipping skill '%s': archive contains no SKILL.md", entry.name) return None @@ -5305,20 +5329,26 @@ def _skill_from_files(self, entry: _McpSkillIndexEntry, files: dict[str, bytes]) # ``path`` records the archive's origin URL; it is informational only, as the # skill and its resources are served entirely from memory (no filesystem access). - return FileSkill( - frontmatter=frontmatter, - content=content, - path=cast(str, entry.url), - resources=resources, - scripts=[], - ) + try: + return FileSkill( + frontmatter=frontmatter, + content=content, + path=cast(str, entry.url), + resources=resources, + scripts=[], + ) + except ValueError as exc: + logger.warning("Skipping skill '%s': %s", entry.name, exc) + return None @staticmethod def _find_skill_md(files: dict[str, bytes]) -> str | None: - """Return the key of the shallowest ``SKILL.md`` (case-insensitive), or ``None``.""" + """Return the shallowest ``SKILL.md`` key, rejecting manifest paths that differ only by case.""" candidates = [key for key in files if key.rsplit("/", 1)[-1].upper() == SKILL_FILE_NAME.upper()] if not candidates: return None + if len({key.lower() for key in candidates}) != len(candidates): + raise ValueError("Archive contains SKILL.md paths that differ only by case.") # Prefer the shallowest SKILL.md; break ties deterministically by name. return min(candidates, key=lambda key: (key.count("/"), key)) @@ -5386,9 +5416,8 @@ class MCPSkillsSource(SkillsSource): archive are surfaced as read-only resources only; MCP-delivered scripts are never discovered as runnable. - Archive member paths are compared case-insensitively, matching resource lookup. - The first file's spelling and content are retained; later colliding members - are skipped with a warning. + Archive resource names that differ only by case, or members that normalize + to the same path, skip the whole archive skill with a warning. Entries whose type has no registered handler (e.g. ``mcp-resource-template``) are skipped. diff --git a/python/packages/core/tests/core/test_mcp_skills.py b/python/packages/core/tests/core/test_mcp_skills.py index ac7b122d4ed..4b8bf6994d4 100644 --- a/python/packages/core/tests/core/test_mcp_skills.py +++ b/python/packages/core/tests/core/test_mcp_skills.py @@ -1536,7 +1536,7 @@ async def test_zip_slip_archive_skips_whole_skill(self) -> None: class TestMCPSkillsSourceArchiveCollisions: - """Colliding archive members warn and preserve the first file through discovery.""" + """Colliding archive members reject only the affected skill.""" @pytest.mark.parametrize( "alias", @@ -1553,7 +1553,7 @@ class TestMCPSkillsSourceArchiveCollisions: @pytest.mark.parametrize("alias_first", [False, True]) @pytest.mark.parametrize("identical", [False, True]) @pytest.mark.parametrize("with_digest", [False, True]) - async def test_colliding_resources_keep_first_file_and_warn( + async def test_colliding_resources_reject_skill_and_warn( self, alias: str, alias_first: bool, identical: bool, with_digest: bool, caplog: pytest.LogCaptureFixture ) -> None: url = "skill://archives/packaged-skill.zip" @@ -1572,24 +1572,15 @@ async def test_colliding_resources_keep_first_file_and_warn( for _ in range(2): skills = await source.get_skills(_SOURCE_CTX) - assert len(skills) == 1 - for resource_name in ("refs/policy.md", "REFS/POLICY.MD"): - resource = await skills[0].get_resource(resource_name) - assert resource is not None - assert await resource.read() == "First resource." - other = await skills[0].get_resource("refs/other.md") - assert other is not None - assert await other.read() == "Unaffected resource." - - collisions = [record for record in caplog.records if "duplicate archive member" in record.getMessage()] - assert len(collisions) == 2 - assert all(record.levelname == "WARNING" for record in collisions) - assert all("keeping the first file" in record.getMessage() for record in collisions) - assert all("Substituted resource." not in record.getMessage() for record in collisions) - - @pytest.mark.parametrize("alias", ["SKILL.md", ".//SKILL.md", "/SKILL.md", "skill.md", "Skill.MD"]) + assert skills == [] + + warnings = [record for record in caplog.records if record.levelname == "WARNING"] + assert len(warnings) == 2 + assert all("'packaged-skill'" in record.getMessage() for record in warnings) + + @pytest.mark.parametrize("alias", [".//SKILL.md", "/SKILL.md"]) @pytest.mark.parametrize("alias_first", [False, True]) - async def test_colliding_skill_md_keeps_first_file_and_warns( + async def test_duplicate_skill_md_rejects_skill_and_warns( self, alias: str, alias_first: bool, caplog: pytest.LogCaptureFixture ) -> None: url = "skill://archives/packaged-skill.zip" @@ -1605,28 +1596,103 @@ async def test_colliding_skill_md_keeps_first_file_and_warns( _SOURCE_CTX ) - assert len(skills) == 1 - assert skills[0].frontmatter.name == "packaged-skill" - assert "Instructions from an archive." in await skills[0].get_content() + assert skills == [] assert len(caplog.records) == 1 assert caplog.records[0].levelname == "WARNING" - assert "duplicate archive member" in caplog.text + assert "Failed to extract archive" in caplog.text + + @pytest.mark.parametrize( + ("manifest", "variant"), + [ + ("SKILL.md", "skill.md"), + ("SKILL.md", "Skill.MD"), + ("nested/SKILL.md", "nested/skill.md"), + ("nested/SKILL.md", "NESTED/SKILL.md"), + ], + ) + @pytest.mark.parametrize("variant_first", [False, True]) + async def test_case_variant_manifests_skip_only_affected_skill( + self, manifest: str, variant: str, variant_first: bool, caplog: pytest.LogCaptureFixture + ) -> None: + url = "skill://archives/packaged-skill.zip" + manifests = [ + (manifest, ARCHIVE_SKILL_MD.encode()), + (variant, ARCHIVE_SKILL_MD.replace("Instructions from an archive.", "Other instructions.").encode()), + ] + if variant_first: + manifests.reverse() + archive = _make_zip(manifests) + index_data = json.loads(SAMPLE_SKILL_INDEX) + index_data["skills"].extend(json.loads(_make_archive_index("packaged-skill", url))["skills"]) + client = _archive_client(json.dumps(index_data), url, archive, "application/zip") + + skills = await MCPSkillsSource(client=client).get_skills(_SOURCE_CTX) + + assert [skill.frontmatter.name for skill in skills] == ["unit-converter"] + assert len(caplog.records) == 1 + assert caplog.records[0].levelname == "WARNING" + assert "'packaged-skill'" in caplog.text + assert "SKILL.md paths that differ only by case" in caplog.text + + @pytest.mark.parametrize( + ("manifest", "other"), + [("SKILL.md", "nested/skill.md"), ("a/SKILL.md", "b/skill.md")], + ) + async def test_manifests_in_distinct_directories_are_not_case_variants(self, manifest: str, other: str) -> None: + url = "skill://archives/packaged-skill.zip" + archive = _make_zip([ + (manifest, ARCHIVE_SKILL_MD.encode()), + (other, ARCHIVE_SKILL_MD.encode()), + ]) + index = _make_archive_index("packaged-skill", url) + + skills = await MCPSkillsSource(client=_archive_client(index, url, archive, "application/zip")).get_skills( + _SOURCE_CTX + ) + + assert [skill.frontmatter.name for skill in skills] == ["packaged-skill"] - async def test_collision_does_not_skip_other_skills(self, caplog: pytest.LogCaptureFixture) -> None: + @pytest.mark.parametrize("duplicate", ["./reference.md", "REFERENCE.md"]) + async def test_collision_does_not_skip_other_skills(self, duplicate: str, caplog: pytest.LogCaptureFixture) -> None: url = "skill://archives/packaged-skill.zip" index_data = json.loads(SAMPLE_SKILL_INDEX) index_data["skills"].extend(json.loads(_make_archive_index("packaged-skill", url))["skills"]) archive = _make_zip([ ("SKILL.md", ARCHIVE_SKILL_MD.encode()), ("reference.md", b"First."), - ("./reference.md", b"Second."), + (duplicate, b"Second."), ]) client = _archive_client(json.dumps(index_data), url, archive, "application/zip") skills = await MCPSkillsSource(client=client).get_skills(_SOURCE_CTX) - assert sorted(skill.frontmatter.name for skill in skills) == ["packaged-skill", "unit-converter"] - assert "duplicate archive member" in caplog.text + assert [skill.frontmatter.name for skill in skills] == ["unit-converter"] + assert "'packaged-skill'" in caplog.text + + async def test_distinct_resource_paths_load_with_case_insensitive_lookup(self) -> None: + url = "skill://archives/packaged-skill.zip" + archive = _make_zip([ + ("SKILL.md", ARCHIVE_SKILL_MD.encode()), + ("reference.md", b"Root resource."), + ("REFERENCE.MD/nested.md", b"Nested resource."), + ("refs/one.md", b"One."), + ("REFS/two.md", b"Two."), + ]) + index = _make_archive_index("packaged-skill", url) + skills = await MCPSkillsSource(client=_archive_client(index, url, archive, "application/zip")).get_skills( + _SOURCE_CTX + ) + + assert len(skills) == 1 + for name, content in ( + ("REFERENCE.MD", "Root resource."), + ("reference.md/NESTED.MD", "Nested resource."), + ("REFS/ONE.MD", "One."), + ("refs/two.md", "Two."), + ): + resource = await skills[0].get_resource(name) + assert resource is not None + assert await resource.read() == content class TestMCPSkillsSourceArchiveDigest: @@ -1941,30 +2007,20 @@ def test_duplicate_members_count_toward_file_limit(self) -> None: with pytest.raises(ValueError, match="file count"): _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 1, 1024 * 1024) - def test_skipped_duplicate_is_not_decompressed(self, caplog: pytest.LogCaptureFixture) -> None: - from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory, _read_member_with_limit - - archive = _make_zip([("reference.md", b"First."), ("./reference.md", b"x" * 100)]) - with patch("agent_framework._skills._read_member_with_limit", wraps=_read_member_with_limit) as read: - files = _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 20, len(b"First.")) + def test_duplicate_normalized_path_rejects_archive(self) -> None: + from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory - assert files == {"reference.md": b"First."} - read.assert_called_once() - assert "duplicate archive member" in caplog.text + archive = _make_zip([("reference.md", b"First."), ("./reference.md", b"Second.")]) + with pytest.raises(ValueError, match="Duplicate archive member"): + _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 20, 1024 * 1024) - @pytest.mark.parametrize("first_name", ["reference.md", "REFERENCE.md"]) - def test_case_collision_keeps_first_name_and_warns(self, first_name: str, caplog: pytest.LogCaptureFixture) -> None: + def test_case_variants_are_extracted_as_is(self) -> None: from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory - second_name = "REFERENCE.md" if first_name == "reference.md" else "reference.md" - archive = _make_zip([(first_name, b"First."), (second_name, b"Second.")]) - - files = _extract_archive_to_memory(archive, _ArchiveFormat.ZIP, 20, 1024 * 1024) + entries = {"reference.md": b"First.", "REFERENCE.md": b"Second."} + files = _extract_archive_to_memory(_make_zip(entries), _ArchiveFormat.ZIP, 20, 1024 * 1024) - assert files == {first_name: b"First."} - assert len(caplog.records) == 1 - assert caplog.records[0].levelname == "WARNING" - assert "duplicate archive member" in caplog.text + assert files == entries def test_distinct_lowercase_resource_names_are_preserved(self, caplog: pytest.LogCaptureFixture) -> None: from agent_framework._skills import _ArchiveFormat, _extract_archive_to_memory diff --git a/python/packages/core/tests/core/test_skills.py b/python/packages/core/tests/core/test_skills.py index 944c7d74a18..bfb3e63d12e 100644 --- a/python/packages/core/tests/core/test_skills.py +++ b/python/packages/core/tests/core/test_skills.py @@ -2583,6 +2583,86 @@ async def test_resources_populated(self, tmp_path: Path) -> None: # --------------------------------------------------------------------------- +class TestFileSkillNameCollisions: + @pytest.mark.parametrize("kind", ["resource", "script"]) + @pytest.mark.parametrize("names", [("readme.md", "README.md"), ("refs/one.md", "REFS/ONE.md")]) + @pytest.mark.parametrize("reverse", [False, True]) + def test_constructor_rejects_names_differing_only_by_case( + self, kind: str, names: tuple[str, str], reverse: bool + ) -> None: + names = (names[1], names[0]) if reverse else names + resources = [InlineSkillResource(name=name, content="data") for name in names] + scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names] + with pytest.raises(ValueError, match=f"{kind} names that differ only by case"): + FileSkill( + frontmatter=SkillFrontmatter(name="example", description="Example."), + content="Instructions.", + path=_ABS, + resources=resources if kind == "resource" else [], + scripts=scripts if kind == "script" else [], + ) + + async def test_resource_and_script_names_are_checked_separately(self) -> None: + resource = InlineSkillResource(name="run.py", content="data") + script = FileSkillScript(name="RUN.py", full_path=f"{_ABS}\\RUN.py") + skill = FileSkill( + frontmatter=SkillFrontmatter(name="example", description="Example."), + content="Instructions.", + path=_ABS, + resources=[resource], + scripts=[script], + ) + assert await skill.get_resource("RUN.PY") is resource + assert await skill.get_script("run.py") is script + + @pytest.mark.parametrize("names", [("\u03a3.md", "\u03c2.md"), ("stra\u00dfe.md", "strasse.md")]) + async def test_unicode_names_with_distinct_lowercase_keys_remain_distinct(self, names: tuple[str, str]) -> None: + resources = [InlineSkillResource(name=name, content=name) for name in names] + scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names] + skill = FileSkill( + frontmatter=SkillFrontmatter(name="example", description="Example."), + content="Instructions.", + path=_ABS, + resources=resources, + scripts=scripts, + ) + + for resource, script in zip(resources, scripts): + assert await skill.get_resource(resource.name.lower()) is resource + assert await skill.get_script(script.name.lower()) is script + + async def test_distinct_names_allow_case_insensitive_lookup(self) -> None: + names = ["readme.md", "refs/one.md", "REFS/two.md"] + resources = [InlineSkillResource(name=name, content=name) for name in names] + scripts = [FileSkillScript(name=name, full_path=f"{_ABS}\\{name}") for name in names] + skill = FileSkill( + frontmatter=SkillFrontmatter(name="example", description="Example."), + content="Instructions.", + path=_ABS, + resources=resources, + scripts=scripts, + ) + for resource, script in zip(resources, scripts): + assert await skill.get_resource(resource.name.upper()) is resource + assert await skill.get_script(script.name.upper()) is script + + async def test_filesystem_collision_skips_only_affected_skill( + self, tmp_path: Path, caplog: pytest.LogCaptureFixture + ) -> None: + _write_skill(tmp_path, "bad") + _write_skill(tmp_path, "good") + original = FileSkillsSource._discover_script_files + + def discover_script_files(self: FileSkillsSource, skill_path: str, skill_name: str) -> list[str]: + return ["run.py", "RUN.py"] if skill_name == "bad" else original(self, skill_path, skill_name) + + with patch.object(FileSkillsSource, "_discover_script_files", discover_script_files): + skills = await FileSkillsSource(tmp_path).get_skills(_SOURCE_CTX) + + assert [skill.frontmatter.name for skill in skills] == ["good"] + assert "Skipping skill 'bad'" in caplog.text + + class TestLoadSkillFormatting: """Tests for _load_skill output formatting differences between file-based and code-defined skills."""