fix: address Copilot review round 12 on #2251
All three findings were the same underlying inconsistency: URI comparisons on raw strings, in a flow that elsewhere deliberately treats normalized equivalents as the same resource. One `skillUriIdentity` helper now backs every comparison, so they cannot disagree. - skills.ts: `manifest-missing-self` compares identities, so a manifest listing the RFC-equivalent `skill://demo/%53KILL.md` is recognized as the entry's own file — it is fetchable as that file, so reporting it missing was the tool disagreeing with itself. - skills.ts: `skillEntriesMatch` normalizes the entry URI and every manifest URI before comparing, so a server that canonicalizes an escape between the listing and the fetch is not reported as a changed snapshot. - SkillsScreen: the `wrongUri` check uses the same identity, so a canonicalizing server is not accused of answering for a different skill — the read path already accepts exactly that equivalence. - skills.ts: apply the Agent Skills name grammar to the RAW value. Trimming first let `" demo "` pass, and whitespace is not in the grammar — so an entry could report "Conforms" with a name that can never equal its URI path segment. The trimmed copy now only distinguishes absent from invalid. - skills.ts: add `malformed-description` for a description above the 1024-character Agent Skills limit, with boundary coverage. - inspectorClient-skills.test: justify the `as unknown as` per AGENTS.md — both fields are `private` with no public setter, the asserted shape is exactly what the class declares, and the alternative is a live connection. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018kfrH3uRNUM4JAk1reKtyY Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
parent
18724b2338
commit
bd28a36f23
4 changed files with 146 additions and 8 deletions
|
|
@ -24,6 +24,7 @@ import {
|
||||||
checkSkillConformance,
|
checkSkillConformance,
|
||||||
skillDisplayName,
|
skillDisplayName,
|
||||||
skillEntriesMatch,
|
skillEntriesMatch,
|
||||||
|
skillUriIdentity,
|
||||||
totalSkillBytes,
|
totalSkillBytes,
|
||||||
verifySkillResource,
|
verifySkillResource,
|
||||||
type SkillIssue,
|
type SkillIssue,
|
||||||
|
|
@ -544,7 +545,12 @@ export function SkillsScreen({
|
||||||
writeFetched({
|
writeFetched({
|
||||||
entry,
|
entry,
|
||||||
issues: checkSkillConformance(entry),
|
issues: checkSkillConformance(entry),
|
||||||
wrongUri: entry.uri !== selected.uri,
|
// Compared by identity, not raw string: a server that canonicalizes
|
||||||
|
// an escape has answered for the same resource, and calling that
|
||||||
|
// "a different URI" would be the tool disagreeing with the read
|
||||||
|
// path, which accepts exactly that equivalence.
|
||||||
|
wrongUri:
|
||||||
|
skillUriIdentity(entry.uri) !== skillUriIdentity(selected.uri),
|
||||||
// Compared semantically — see `skillEntriesMatch` for why a
|
// Compared semantically — see `skillEntriesMatch` for why a
|
||||||
// `JSON.stringify` comparison would report key order and manifest
|
// `JSON.stringify` comparison would report key order and manifest
|
||||||
// order as differences.
|
// order as differences.
|
||||||
|
|
|
||||||
|
|
@ -45,6 +45,21 @@ describe("InspectorClient skills methods (#2234)", () => {
|
||||||
);
|
);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* A structural view onto two private fields, so the tests can stub the SDK
|
||||||
|
* client and set `capabilities` without connecting.
|
||||||
|
*
|
||||||
|
* The double cast is justified rather than incidental: `InspectorClient`
|
||||||
|
* declares both members `private`, so no single `as` relates it to a type
|
||||||
|
* that exposes them, and there is no public setter for either — the public
|
||||||
|
* path is `connect()`, which needs a transport, a live server and a
|
||||||
|
* handshake to reach the same state. It is safe because the shape asserted
|
||||||
|
* here is exactly the shape the class declares (`client` is the SDK client;
|
||||||
|
* `capabilities` is `ServerCapabilities | undefined`), so a rename or a type
|
||||||
|
* change on either field breaks these tests at the first use rather than
|
||||||
|
* silently passing. The same seam is used by
|
||||||
|
* `inspectorClient-raw-wire.test.ts`.
|
||||||
|
*/
|
||||||
function internals(client: InspectorClient): SkillsInternals {
|
function internals(client: InspectorClient): SkillsInternals {
|
||||||
return client as unknown as SkillsInternals;
|
return client as unknown as SkillsInternals;
|
||||||
}
|
}
|
||||||
|
|
|
||||||
|
|
@ -11,6 +11,7 @@ import {
|
||||||
isSkillsExtensionSupported,
|
isSkillsExtensionSupported,
|
||||||
normalizeSkillUri,
|
normalizeSkillUri,
|
||||||
skillEntriesMatch,
|
skillEntriesMatch,
|
||||||
|
skillUriIdentity,
|
||||||
sha256Digest,
|
sha256Digest,
|
||||||
skillDisplayName,
|
skillDisplayName,
|
||||||
skillNameFromUri,
|
skillNameFromUri,
|
||||||
|
|
@ -191,6 +192,21 @@ describe("normalizeSkillUri", () => {
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|
||||||
|
describe("skillUriIdentity", () => {
|
||||||
|
it("is the normalized form when the URI parses", () => {
|
||||||
|
expect(skillUriIdentity("skill://demo/a/../SKILL.md")).toBe(
|
||||||
|
"skill://demo/SKILL.md",
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it("falls back to the raw string, keeping two bad URIs distinct", () => {
|
||||||
|
expect(skillUriIdentity("not a uri")).toBe("not a uri");
|
||||||
|
expect(skillUriIdentity("not a uri")).not.toBe(
|
||||||
|
skillUriIdentity("also not a uri"),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
describe("skillEntriesMatch", () => {
|
describe("skillEntriesMatch", () => {
|
||||||
const base = (): SkillEntry => ({
|
const base = (): SkillEntry => ({
|
||||||
uri: "skill://demo/SKILL.md",
|
uri: "skill://demo/SKILL.md",
|
||||||
|
|
@ -237,6 +253,20 @@ describe("skillEntriesMatch", () => {
|
||||||
).toBe(true);
|
).toBe(true);
|
||||||
});
|
});
|
||||||
|
|
||||||
|
it("treats RFC-equivalent URI spellings as the same entry", () => {
|
||||||
|
// A server that canonicalizes an escape between the listing and the fetch
|
||||||
|
// has not changed the skill, so it must not read as a new snapshot.
|
||||||
|
const encoded: SkillEntry = {
|
||||||
|
...base(),
|
||||||
|
uri: "skill://demo/%53KILL.md",
|
||||||
|
resources: [
|
||||||
|
{ uri: "skill://demo/%53KILL.md", digest: DIGEST, size: 20 },
|
||||||
|
{ uri: "skill://demo/x/../ref.md", digest: DIGEST, size: 10 },
|
||||||
|
],
|
||||||
|
};
|
||||||
|
expect(skillEntriesMatch(base(), encoded)).toBe(true);
|
||||||
|
});
|
||||||
|
|
||||||
it("still sees a real difference", () => {
|
it("still sees a real difference", () => {
|
||||||
expect(
|
expect(
|
||||||
skillEntriesMatch(base(), {
|
skillEntriesMatch(base(), {
|
||||||
|
|
@ -307,6 +337,16 @@ describe("checkSkillConformance", () => {
|
||||||
}
|
}
|
||||||
});
|
});
|
||||||
|
|
||||||
|
it("applies the name grammar to the RAW value, not a trimmed copy", () => {
|
||||||
|
// Trimming first would let `" demo "` through — and whitespace is not in
|
||||||
|
// the grammar, so the entry would report "Conforms" with a name that can
|
||||||
|
// never equal its URI path segment.
|
||||||
|
const issues = checkSkillConformance(
|
||||||
|
entry({ frontmatter: { name: " demo ", description: "d" } }),
|
||||||
|
);
|
||||||
|
expect(issues.map((i) => i.code)).toContain("malformed-name");
|
||||||
|
});
|
||||||
|
|
||||||
it("accepts the names the Agent Skills format allows", () => {
|
it("accepts the names the Agent Skills format allows", () => {
|
||||||
for (const name of ["a", "demo", "data-analysis", "a1-b2-c3"]) {
|
for (const name of ["a", "demo", "data-analysis", "a1-b2-c3"]) {
|
||||||
const issues = checkSkillConformance(
|
const issues = checkSkillConformance(
|
||||||
|
|
@ -330,6 +370,21 @@ describe("checkSkillConformance", () => {
|
||||||
expect(issues.map((i) => i.code)).toEqual(["missing-name"]);
|
expect(issues.map((i) => i.code)).toEqual(["missing-name"]);
|
||||||
});
|
});
|
||||||
|
|
||||||
|
it("reports a description above the 1024-character limit", () => {
|
||||||
|
const issues = checkSkillConformance(
|
||||||
|
entry({ frontmatter: { name: "demo", description: "d".repeat(1025) } }),
|
||||||
|
);
|
||||||
|
expect(issues.map((i) => i.code)).toEqual(["malformed-description"]);
|
||||||
|
expect(issues[0].severity).toBe("error");
|
||||||
|
});
|
||||||
|
|
||||||
|
it("accepts a description exactly at the limit", () => {
|
||||||
|
const issues = checkSkillConformance(
|
||||||
|
entry({ frontmatter: { name: "demo", description: "d".repeat(1024) } }),
|
||||||
|
);
|
||||||
|
expect(issues).toEqual([]);
|
||||||
|
});
|
||||||
|
|
||||||
it("reports a missing description as an error", () => {
|
it("reports a missing description as an error", () => {
|
||||||
// SEP-2640 requires `description`, so an absent one is a format violation
|
// SEP-2640 requires `description`, so an absent one is a format violation
|
||||||
// and must not read as "0 errors" in the conformance summary.
|
// and must not read as "0 errors" in the conformance summary.
|
||||||
|
|
@ -388,6 +443,20 @@ describe("checkSkillConformance", () => {
|
||||||
expect(issues[0].resourceUri).toBe("skill://demo/ref.md");
|
expect(issues[0].resourceUri).toBe("skill://demo/ref.md");
|
||||||
});
|
});
|
||||||
|
|
||||||
|
it("accepts a self-entry listed in an RFC-equivalent spelling", () => {
|
||||||
|
// The manifest names the same file the entry does, and it is fetchable as
|
||||||
|
// that file — reporting it missing would be the tool disagreeing with
|
||||||
|
// itself about which URIs are the same resource.
|
||||||
|
const issues = checkSkillConformance(
|
||||||
|
entry({
|
||||||
|
resources: [
|
||||||
|
{ uri: "skill://demo/%53KILL.md", digest: DIGEST, size: 20 },
|
||||||
|
],
|
||||||
|
}),
|
||||||
|
);
|
||||||
|
expect(issues.map((i) => i.code)).not.toContain("manifest-missing-self");
|
||||||
|
});
|
||||||
|
|
||||||
it("reports a manifest that omits the skill's own SKILL.md", () => {
|
it("reports a manifest that omits the skill's own SKILL.md", () => {
|
||||||
// A manifest is the complete file set, so one without the entry file is
|
// A manifest is the complete file set, so one without the entry file is
|
||||||
// not "a skill with no extras" — it cannot be checked against the skill.
|
// not "a skill with no extras" — it cannot be checked against the skill.
|
||||||
|
|
|
||||||
|
|
@ -68,6 +68,9 @@ const DIGEST_PATTERN = /^sha256:[0-9a-f]{64}$/;
|
||||||
const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
|
||||||
const SKILL_NAME_MAX_LENGTH = 64;
|
const SKILL_NAME_MAX_LENGTH = 64;
|
||||||
|
|
||||||
|
/** The Agent Skills limit on `frontmatter.description`. */
|
||||||
|
const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* What the server declared under `io.modelcontextprotocol/skills`. The only
|
* What the server declared under `io.modelcontextprotocol/skills`. The only
|
||||||
* sub-option SEP-2640 defines is `directoryRead`, which gates
|
* sub-option SEP-2640 defines is `directoryRead`, which gates
|
||||||
|
|
@ -180,6 +183,19 @@ export function skillNameFromUri(uri: string): string | undefined {
|
||||||
return segment.length > 0 ? segment : undefined;
|
return segment.length > 0 ? segment : undefined;
|
||||||
}
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* The comparison identity of a resource URI: its normalized form, falling back
|
||||||
|
* to the raw string when it does not parse.
|
||||||
|
*
|
||||||
|
* Every URI comparison in this module and in the screen goes through this, so
|
||||||
|
* they cannot disagree about whether two spellings name the same file. The raw
|
||||||
|
* fallback is deliberate: two *different* unparseable URIs must stay distinct
|
||||||
|
* rather than both collapsing to one `undefined` identity.
|
||||||
|
*/
|
||||||
|
export function skillUriIdentity(uri: string): string {
|
||||||
|
return normalizeSkillUri(uri) ?? uri;
|
||||||
|
}
|
||||||
|
|
||||||
/**
|
/**
|
||||||
* The label a UI shows for a skill: the declared name, falling back to the URI
|
* The label a UI shows for a skill: the declared name, falling back to the URI
|
||||||
* path segment, falling back to the raw URI. Never empty, so a list row is
|
* path segment, falling back to the raw URI. Never empty, so a list row is
|
||||||
|
|
@ -197,6 +213,7 @@ export type SkillIssueCode =
|
||||||
| "missing-name"
|
| "missing-name"
|
||||||
| "malformed-name"
|
| "malformed-name"
|
||||||
| "missing-description"
|
| "missing-description"
|
||||||
|
| "malformed-description"
|
||||||
| "malformed-uri"
|
| "malformed-uri"
|
||||||
| "name-path-mismatch"
|
| "name-path-mismatch"
|
||||||
| "missing-digest"
|
| "missing-digest"
|
||||||
|
|
@ -238,7 +255,11 @@ export interface SkillIssue {
|
||||||
*/
|
*/
|
||||||
export function checkSkillConformance(entry: SkillEntry): SkillIssue[] {
|
export function checkSkillConformance(entry: SkillEntry): SkillIssue[] {
|
||||||
const issues: SkillIssue[] = [];
|
const issues: SkillIssue[] = [];
|
||||||
const declaredName = entry.frontmatter.name?.trim();
|
// The RAW value is what the grammar is applied to — trimming first would let
|
||||||
|
// `" demo "` pass, and whitespace is not in the Agent Skills name grammar.
|
||||||
|
// The trimmed copy exists only to tell "absent" from "present but invalid".
|
||||||
|
const rawName = entry.frontmatter.name;
|
||||||
|
const declaredName = rawName?.trim() ? rawName : undefined;
|
||||||
const uriName = skillNameFromUri(entry.uri);
|
const uriName = skillNameFromUri(entry.uri);
|
||||||
|
|
||||||
if (!declaredName) {
|
if (!declaredName) {
|
||||||
|
|
@ -251,13 +272,15 @@ export function checkSkillConformance(entry: SkillEntry): SkillIssue[] {
|
||||||
declaredName.length > SKILL_NAME_MAX_LENGTH ||
|
declaredName.length > SKILL_NAME_MAX_LENGTH ||
|
||||||
!SKILL_NAME_PATTERN.test(declaredName)
|
!SKILL_NAME_PATTERN.test(declaredName)
|
||||||
) {
|
) {
|
||||||
|
// Reaches here for `" demo "` too: the grammar sees the untrimmed value.
|
||||||
issues.push({
|
issues.push({
|
||||||
code: "malformed-name",
|
code: "malformed-name",
|
||||||
severity: "error",
|
severity: "error",
|
||||||
message: `frontmatter.name "${declaredName}" is not a valid Agent Skills name: 1–${SKILL_NAME_MAX_LENGTH} lowercase alphanumerics and hyphens, with no leading, trailing or consecutive hyphen.`,
|
message: `frontmatter.name "${declaredName}" is not a valid Agent Skills name: 1–${SKILL_NAME_MAX_LENGTH} lowercase alphanumerics and hyphens, with no leading, trailing or consecutive hyphen.`,
|
||||||
});
|
});
|
||||||
}
|
}
|
||||||
if (!entry.frontmatter.description?.trim()) {
|
const rawDescription = entry.frontmatter.description;
|
||||||
|
if (!rawDescription?.trim()) {
|
||||||
// An error, not a warning: SEP-2640 requires `description` on every skill,
|
// An error, not a warning: SEP-2640 requires `description` on every skill,
|
||||||
// so an absent one is a format violation and must not read as "0 errors".
|
// so an absent one is a format violation and must not read as "0 errors".
|
||||||
issues.push({
|
issues.push({
|
||||||
|
|
@ -265,6 +288,12 @@ export function checkSkillConformance(entry: SkillEntry): SkillIssue[] {
|
||||||
severity: "error",
|
severity: "error",
|
||||||
message: "frontmatter.description is required but missing or empty.",
|
message: "frontmatter.description is required but missing or empty.",
|
||||||
});
|
});
|
||||||
|
} else if (rawDescription.length > SKILL_DESCRIPTION_MAX_LENGTH) {
|
||||||
|
issues.push({
|
||||||
|
code: "malformed-description",
|
||||||
|
severity: "error",
|
||||||
|
message: `frontmatter.description is ${rawDescription.length} characters, above the ${SKILL_DESCRIPTION_MAX_LENGTH}-character limit.`,
|
||||||
|
});
|
||||||
}
|
}
|
||||||
if (uriName === undefined) {
|
if (uriName === undefined) {
|
||||||
issues.push({
|
issues.push({
|
||||||
|
|
@ -320,7 +349,16 @@ export function checkSkillConformance(entry: SkillEntry): SkillIssue[] {
|
||||||
// therefore not "a skill with no extra files" — it is a manifest that cannot
|
// therefore not "a skill with no extra files" — it is a manifest that cannot
|
||||||
// be checked against what the skill actually is, and reporting `Conforms`
|
// be checked against what the skill actually is, and reporting `Conforms`
|
||||||
// for it would be a wrong answer rather than a missing one.
|
// for it would be a wrong answer rather than a missing one.
|
||||||
if (!entry.resources.some((resource) => resource.uri === entry.uri)) {
|
// Compared on the normalized identity, like every other URI comparison here:
|
||||||
|
// a manifest listing the RFC-equivalent `skill://demo/%53KILL.md` names the
|
||||||
|
// same file the entry does, and is fetchable as that file, so calling it a
|
||||||
|
// missing self-entry would be the tool disagreeing with itself.
|
||||||
|
const entryIdentity = skillUriIdentity(entry.uri);
|
||||||
|
if (
|
||||||
|
!entry.resources.some(
|
||||||
|
(resource) => skillUriIdentity(resource.uri) === entryIdentity,
|
||||||
|
)
|
||||||
|
) {
|
||||||
issues.push({
|
issues.push({
|
||||||
code: "manifest-missing-self",
|
code: "manifest-missing-self",
|
||||||
severity: "error",
|
severity: "error",
|
||||||
|
|
@ -353,7 +391,7 @@ export function checkSkillConformance(entry: SkillEntry): SkillIssue[] {
|
||||||
// sent. Unparseable URIs fall back to the raw string: they are already
|
// sent. Unparseable URIs fall back to the raw string: they are already
|
||||||
// reported by the root check, and normalizing them all to `undefined`
|
// reported by the root check, and normalizing them all to `undefined`
|
||||||
// would make two different bad URIs look like one duplicate.
|
// would make two different bad URIs look like one duplicate.
|
||||||
const identity = normalizeSkillUri(resource.uri) ?? resource.uri;
|
const identity = skillUriIdentity(resource.uri);
|
||||||
if (seenUris.has(identity)) {
|
if (seenUris.has(identity)) {
|
||||||
issues.push({
|
issues.push({
|
||||||
code: "duplicate-resource",
|
code: "duplicate-resource",
|
||||||
|
|
@ -478,13 +516,23 @@ export function skillEntriesMatch(a: SkillEntry, b: SkillEntry): boolean {
|
||||||
* a set; every other array keeps its order.
|
* a set; every other array keeps its order.
|
||||||
*/
|
*/
|
||||||
function canonicalEntry(entry: SkillEntry): string {
|
function canonicalEntry(entry: SkillEntry): string {
|
||||||
const { resources, ...rest } = entry;
|
const { resources, uri, ...rest } = entry;
|
||||||
|
// URIs are compared by IDENTITY, so a server that canonicalizes an escape
|
||||||
|
// between the listing and the fetch is not reported as a changed snapshot.
|
||||||
const manifest = Array.isArray(resources)
|
const manifest = Array.isArray(resources)
|
||||||
? [...resources]
|
? [...resources]
|
||||||
.sort((x, y) => String(x?.uri).localeCompare(String(y?.uri)))
|
.map((resource) => ({
|
||||||
|
...resource,
|
||||||
|
uri: skillUriIdentity(String(resource?.uri)),
|
||||||
|
}))
|
||||||
|
.sort((x, y) => x.uri.localeCompare(y.uri))
|
||||||
.map(canonicalize)
|
.map(canonicalize)
|
||||||
: resources;
|
: resources;
|
||||||
return JSON.stringify({ ...sortKeys(rest), resources: manifest });
|
return JSON.stringify({
|
||||||
|
...sortKeys(rest),
|
||||||
|
uri: skillUriIdentity(uri),
|
||||||
|
resources: manifest,
|
||||||
|
});
|
||||||
}
|
}
|
||||||
|
|
||||||
/** Object keys sorted recursively; array ORDER is preserved throughout. */
|
/** Object keys sorted recursively; array ORDER is preserved throughout. */
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue