feat: Skills extension phase 3 — CLI, TUI, directory reads, frontmatter check

Closes #2248.

Completes SEP-2640 support across all three clients, and closes the one
obligation #2234 deliberately left open.

- `checkSkillFrontmatterMatch` compares a served SKILL.md's own YAML
  frontmatter against the entry the listing advertised, field by field. No
  digest can cover this: a digest is taken over the bytes the server served,
  so it proves the file was not altered in transit and says nothing about
  whether the listing described it honestly. Needs a real YAML parser; `yaml`
  was already a root dependency, so this adds no package — but it does newly
  put it on core/'s import graph, hence the three bundler `external` lists.

- `resources/directory/read`: result schemas defined against the normative
  text, `InspectorClient.readResourceDirectory`, a Directory section on the
  Skills screen, and `--method resources/directory/read` in the CLI. The
  client refuses the call locally when the server did not declare
  `directoryRead`, which is the SEP's MUST NOT. A child the directory lists
  but the entry does not is marked `not listed` rather than merged into the
  manifest — the SEP calls a directory result a live observation and forbids
  treating it as extending the manifest.

- CLI: `skills/list`, `skills/get` and `resources/directory/read`, plus
  `--verify` — one NDJSON report per skill, a summary on stderr, exit 7 on a
  violation. Reads are sequential; a conforming manifest may declare 512
  entries.

- TUI: a Skills pane, shown only when the server declares the extension. Each
  row carries its conformance verdict as a glyph as well as a colour, since
  the pane is read over ssh and through script(1). Enter verifies.

- `verifySkills` re-throws `AuthRecoveryRequiredError` rather than recording
  it per file: it says the session's authorization expired, so absorbing it
  would report N identical read failures and swallow the error the TUI and
  the web commands key off to reauthorize.

Two open questions settled, both in code comments where they will be found:
`skills/get` carries no caching attributes because SEP-2640 leaves the
question open in as many words, so requiring them would fail a conforming
server; and there is no `PagedSkillsState` because every consumer of this
list is a whole-catalog verdict — computed over page one of three, "this
server's skills conform" is not merely partial but wrong.

The fixture grows two skills, both for checks that were otherwise
undemonstrable: `lying-listing` (listing and file disagree, digest still
verifies) and `stale-manifest` (serves a file its manifest does not declare).

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ND46Ci64DC3tzBy9aG81Nc
Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-09-07 18:10:37 -04:00
commit 9a8488681e

View file

@ -23,15 +23,15 @@
* machinery (activation, per-skill consent, content-bound approval) is
* implemented here. Surface and verify.
*
* ⚠️ **One SEP-2640 obligation is deliberately NOT checked here: that an entry's
* `frontmatter` matches the fetched `SKILL.md`'s frontmatter field by field.**
* The digest check does not cover it — a digest is taken over the bytes the
* server served, so it proves the file was not tampered with in transit and
* says nothing about whether the *listing* described that file honestly. A
* server can therefore advertise one description, serve a different one, and
* pass every check in this module. Closing it needs a YAML parser, which is a
* new runtime dependency and a placement decision of its own, so it is tracked
* on #2248 rather than half-done here.
* **The frontmatter cross-check closes the gap the digest cannot** (#2248).
* SEP-2640 requires that an entry's `frontmatter` match the fetched `SKILL.md`'s
* frontmatter field by field, and no digest can establish that: a digest is
* taken over the bytes the server served, so it proves the file was not altered
* in transit and says nothing about whether the *listing* described that file
* honestly. A server could advertise one description, serve another, and pass
* every other check in this module. {@link checkSkillFrontmatterMatch} is the
* check; it needs a real YAML parser, and `core/mcp/skillFile.ts` explains why
* that dependency is imported rather than approximated.
*/
import type { ServerCapabilities } from "@modelcontextprotocol/client";
@ -42,6 +42,7 @@ import {
type SkillResource,
} from "./skillsSchemas.js";
import { sha256Bytes } from "./sha256.js";
import { parseSkillFrontmatter, splitSkillFile } from "./skillFile.js";
/** Maximum resource entries a single skill may declare (SEP-2640). */
export const SKILL_MAX_RESOURCE_ENTRIES = 512;
@ -243,7 +244,10 @@ export type SkillIssueCode =
| "resource-outside-skill-root"
| "manifest-missing-self"
| "resource-limit-exceeded"
| "size-limit-exceeded";
| "size-limit-exceeded"
| "frontmatter-absent"
| "frontmatter-unparsable"
| "frontmatter-mismatch";
/**
* `error` marks a **MUST** of SEP-2640 that the server broke, so a manifest
@ -646,6 +650,32 @@ export function base64ToBytes(blob: string): Uint8Array {
return bytes;
}
/**
* The content a `resources/read` returned for one skill file. Either `text` (a
* `TextResourceContents`) or `blob` (base64, a `BlobResourceContents`).
*/
export interface SkillFileContents {
text?: string;
blob?: string;
mimeType?: string;
}
/**
* The raw bytes of a skill file, as fetched — the bytes its digest was taken
* over.
*
* Throws for a result carrying neither `text` nor `blob`. That is a server bug,
* and it must not be quietly treated as empty content: an empty `Uint8Array`
* has a perfectly good SHA-256, so a silent fallback would report a *digest
* mismatch* — a confident, wrong diagnosis — instead of "this response carried
* no content at all". Callers surface the throw as a per-file read failure.
*/
export function skillFileBytes(contents: SkillFileContents): Uint8Array {
if (typeof contents.text === "string") return textToBytes(contents.text);
if (typeof contents.blob === "string") return base64ToBytes(contents.blob);
throw new Error("resources/read returned neither text nor blob content.");
}
/**
* Verify one fetched skill file against its manifest entry.
*
@ -704,3 +734,105 @@ export async function verifySkillResource(
: {}),
};
}
/**
* Compare the fetched `SKILL.md`'s own frontmatter against the frontmatter the
* entry advertised, field by field — the SEP-2640 obligation a digest cannot
* discharge (#2248).
*
* SEP-2640: *"hosts MUST parse its YAML frontmatter and compare it
* field-by-field against the entry's `frontmatter`. Any discrepancy MUST be
* treated as a verification failure equivalent to a digest mismatch"*. So every
* finding here is an `error`, matching what a digest mismatch reports — the
* spec makes them equivalent and the report must not rank one below the other.
*
* **One finding per differing field, not one per file.** "Frontmatter does not
* match" is unactionable for the server author who has to fix it; "listing says
* `description: A`, file says `description: B`" is the whole diagnosis. The
* union of both sides' keys is walked, so a field present on only one side is
* reported as such rather than silently skipped.
*
* ⚠️ **Only call this with the bytes of the entry's own `SKILL.md`.** The check
* is meaningless against a supporting file, which has no frontmatter to match,
* and would report every one of them as `frontmatter-absent`. Callers select
* the file; this function cannot tell which one it was handed.
*
* Values are compared as **canonical JSON**, so a frontmatter field holding a
* nested mapping compares equal when the two sides agree on content and differ
* only in key order — which is not a discrepancy in either JSON or YAML. Array
* order *is* significant and is preserved, because a YAML sequence is ordered.
*/
export function checkSkillFrontmatterMatch(
entry: SkillEntry,
skillFileText: string,
): SkillIssue[] {
const { frontmatter } = splitSkillFile(skillFileText);
if (frontmatter === undefined) {
return [
{
code: "frontmatter-absent",
severity: "error",
message:
"The served SKILL.md carries no YAML frontmatter block, so the listing's frontmatter cannot be the file's.",
resourceUri: entry.uri,
},
];
}
const parsed = parseSkillFrontmatter(frontmatter);
if ("error" in parsed) {
return [
{
code: "frontmatter-unparsable",
severity: "error",
message: `The served SKILL.md's frontmatter is not valid YAML: ${parsed.error}`,
resourceUri: entry.uri,
},
];
}
const issues: SkillIssue[] = [];
// Sorted so the report is stable across runs — `Object.keys` order follows
// insertion, which is the wire order on one side and the file order on the
// other, and those need not agree even when the content does.
const fields = [
...new Set([
...Object.keys(entry.frontmatter),
...Object.keys(parsed.fields),
]),
].sort();
for (const field of fields) {
const listed = entry.frontmatter[field];
const served = parsed.fields[field];
// `undefined` is the only way "absent" reaches here: JSON has no undefined
// value, and a YAML key written with an empty value parses to `null`, which
// is a present field holding null and compares as one.
if (listed === undefined) {
issues.push({
code: "frontmatter-mismatch",
severity: "error",
message: `The served SKILL.md declares "${field}" but the listing's frontmatter omits it.`,
resourceUri: entry.uri,
});
continue;
}
if (served === undefined) {
issues.push({
code: "frontmatter-mismatch",
severity: "error",
message: `The listing declares "${field}" but the served SKILL.md omits it.`,
resourceUri: entry.uri,
});
continue;
}
const listedJson = JSON.stringify(canonicalize(listed));
const servedJson = JSON.stringify(canonicalize(served));
if (listedJson !== servedJson) {
issues.push({
code: "frontmatter-mismatch",
severity: "error",
message: `Field "${field}" differs: the listing says ${listedJson} but the served SKILL.md says ${servedJson}.`,
resourceUri: entry.uri,
});
}
}
return issues;
}