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
4 changed files with 4750 additions and 191 deletions

View file

@ -27,6 +27,7 @@ import {
ManagedResourcesState,
ManagedResourceTemplatesState,
ManagedPromptsState,
ManagedSkillsState,
MessageLogState,
FetchRequestLogState,
StderrLogState,
@ -40,6 +41,7 @@ import { useManagedTools } from "@inspector/core/react/useManagedTools.js";
import { useManagedResources } from "@inspector/core/react/useManagedResources.js";
import { useManagedResourceTemplates } from "@inspector/core/react/useManagedResourceTemplates.js";
import { useManagedPrompts } from "@inspector/core/react/useManagedPrompts.js";
import { useManagedSkills } from "@inspector/core/react/useManagedSkills.js";
import { useMessageLog } from "@inspector/core/react/useMessageLog.js";
import { useFetchRequestLog } from "@inspector/core/react/useFetchRequestLog.js";
import { useStderrLog } from "@inspector/core/react/useStderrLog.js";
@ -79,6 +81,7 @@ import { InfoTab } from "./components/InfoTab.js";
import { AuthTab } from "./components/AuthTab.js";
import { ResourcesTab } from "./components/ResourcesTab.js";
import { PromptsTab } from "./components/PromptsTab.js";
import { SkillsTab } from "./components/SkillsTab.js";
import { ToolsTab } from "./components/ToolsTab.js";
import { NotificationsTab } from "./components/NotificationsTab.js";
import { HistoryTab } from "./components/HistoryTab.js";
@ -153,6 +156,7 @@ function App({
info?: number;
resources?: number;
prompts?: number;
skills?: number;
tools?: number;
messages?: number;
requests?: number;
@ -244,6 +248,9 @@ function App({
const [managedPromptsStates, setManagedPromptsStates] = useState<
Record<string, ManagedPromptsState>
>({});
const [managedSkillsStates, setManagedSkillsStates] = useState<
Record<string, ManagedSkillsState>
>({});
const [messageLogStates, setMessageLogStates] = useState<
Record<string, MessageLogState>
>({});
@ -293,6 +300,7 @@ function App({
ManagedResourceTemplatesState
> = {};
const newManagedPromptsStates: Record<string, ManagedPromptsState> = {};
const newManagedSkillsStates: Record<string, ManagedSkillsState> = {};
const newMessageLogStates: Record<string, MessageLogState> = {};
const newFetchRequestLogStates: Record<string, FetchRequestLogState> = {};
const newStderrLogStates: Record<string, StderrLogState> = {};
@ -367,6 +375,7 @@ function App({
newManagedResourceTemplatesStates[serverName] =
new ManagedResourceTemplatesState(client);
newManagedPromptsStates[serverName] = new ManagedPromptsState(client);
newManagedSkillsStates[serverName] = new ManagedSkillsState(client);
newMessageLogStates[serverName] = new MessageLogState(client);
newFetchRequestLogStates[serverName] = new FetchRequestLogState(client);
newStderrLogStates[serverName] = new StderrLogState(client);
@ -387,6 +396,10 @@ function App({
...prev,
...newManagedPromptsStates,
}));
setManagedSkillsStates((prev) => ({
...prev,
...newManagedSkillsStates,
}));
setMessageLogStates((prev) => ({ ...prev, ...newMessageLogStates }));
setFetchRequestLogStates((prev) => ({
...prev,
@ -420,6 +433,9 @@ function App({
Object.values(managedPromptsStates).forEach((manager) => {
manager.destroy();
});
Object.values(managedSkillsStates).forEach((manager) => {
manager.destroy();
});
Object.values(messageLogStates).forEach((manager) => {
manager.destroy();
});
@ -441,6 +457,7 @@ function App({
managedResourcesStates,
managedResourceTemplatesStates,
managedPromptsStates,
managedSkillsStates,
messageLogStates,
fetchRequestLogStates,
stderrLogStates,
@ -586,10 +603,28 @@ function App({
selectedInspectorClient,
selectedManagedResourceTemplatesState,
);
const selectedManagedSkillsState = useMemo(
() =>
selectedServer && managedSkillsStates[selectedServer]
? managedSkillsStates[selectedServer]
: null,
[selectedServer, managedSkillsStates],
);
const { prompts: managedPrompts } = useManagedPrompts(
selectedInspectorClient,
selectedManagedPromptsState,
);
const {
skills: managedSkills,
pageCount: managedSkillsPageCount,
error: managedSkillsError,
} = useManagedSkills(selectedInspectorClient, selectedManagedSkillsState);
// A *server-declared* extension, so it is only knowable after connecting —
// unlike the transport-derived `showLoggingTab` / `showRequestsTab` above.
const showSkillsTab =
!!selectedServer &&
!!selectedInspectorClient?.getSkillsExtension() &&
inspectorStatus === "connected";
// Connect — on 401 or mid-session auth recovery, run OAuth then retry.
type TuiOAuthRunResult =
@ -1347,6 +1382,7 @@ function App({
setTabCounts({
resources: managedResources.length || 0,
prompts: managedPrompts.length || 0,
skills: managedSkills.length || 0,
tools: managedTools.length || 0,
messages: inspectorMessages.length || 0,
requests: inspectorFetchRequests.length || 0,
@ -1356,6 +1392,7 @@ function App({
selectedServer,
managedResources,
managedPrompts,
managedSkills,
managedTools,
inspectorMessages,
inspectorFetchRequests,
@ -1430,6 +1467,7 @@ function App({
if (tab.id === "auth" && !showAuthTab) return false;
if (tab.id === "logging" && !showLoggingTab) return false;
if (tab.id === "requests" && !showRequestsTab) return false;
if (tab.id === "skills" && !showSkillsTab) return false;
return true;
})
.map((tab: { id: TabType; label: string; accelerator: string }) => [
@ -1517,6 +1555,7 @@ function App({
"auth",
"resources",
"prompts",
"skills",
"tools",
"messages",
"requests",
@ -1526,6 +1565,7 @@ function App({
if (t === "auth" && !showAuthTab) return false;
if (t === "logging" && !showLoggingTab) return false;
if (t === "requests" && !showRequestsTab) return false;
if (t === "skills" && !showSkillsTab) return false;
return true;
});
const currentIndex = tabs.indexOf(activeTab);
@ -1763,6 +1803,7 @@ function App({
? inspectorClients[selectedServer].getServerType() === "stdio"
: false
}
showSkills={showSkillsTab}
showRequests={
selectedServer && inspectorClients[selectedServer]
? (() => {
@ -1967,6 +2008,34 @@ function App({
)
}
/>
) : activeTab === "skills" &&
currentServerState?.status === "connected" &&
selectedInspectorClient ? (
<SkillsTab
key={`skills-${selectedServer}`}
skills={managedSkills}
pageCount={managedSkillsPageCount}
loadError={managedSkillsError}
inspectorClient={selectedInspectorClient}
width={contentWidth}
height={contentHeight}
focusedPane={
focus === "tabContentDetails"
? "details"
: focus === "tabContentList"
? "list"
: null
}
onAuthRecoveryRequired={onAuthRecoveryRequired}
modalOpen={
!!(
toolTestModal ||
resourceTestModal ||
promptTestModal ||
detailsModal
)
}
/>
) : activeTab === "prompts" &&
currentServerState?.status === "connected" &&
selectedInspectorClient ? (

View file

@ -0,0 +1,416 @@
import React, { useCallback, useEffect, useRef, useState } from "react";
import { Box, Text, useInput, type Key } from "ink";
import { ScrollView, type ScrollViewRef } from "ink-scroll-view";
import type { InspectorClient } from "@inspector/core/mcp/index.js";
import { AuthRecoveryRequiredError } from "@inspector/core/auth/challenge.js";
import {
checkSkillConformance,
skillDisplayName,
type SkillIssue,
} from "@inspector/core/mcp/skills.js";
import {
DYNAMIC_RESOURCES,
type SkillEntry,
} from "@inspector/core/mcp/skillsSchemas.js";
import {
verifySkills,
type SkillVerifyReport,
} from "@inspector/core/mcp/skillsVerification.js";
import { useSelectableList } from "../hooks/useSelectableList.js";
interface SkillsTabProps {
skills: SkillEntry[];
/** Pages the last `skills/list` walk took; shown so pagination is visible. */
pageCount: number;
/** A failed list walk, rendered in place of the list. */
loadError?: Error | null;
inspectorClient: InspectorClient | null;
width: number;
height: number;
focusedPane?: "list" | "details" | null;
onAuthRecoveryRequired?: (error: AuthRecoveryRequiredError) => void;
modalOpen?: boolean;
}
/**
* The character that leads a finding line, by severity. A terminal pane cannot
* lean on colour alone — the Inspector is run over ssh, in tmux, and piped
* through `script(1)` — so severity is carried by a glyph as well as a colour.
*/
const ISSUE_MARK: Record<SkillIssue["severity"], string> = {
error: "✗",
warning: "!",
};
const ISSUE_COLOR: Record<SkillIssue["severity"], string> = {
error: "red",
warning: "yellow",
};
/** Per-file verification glyph, same reasoning as {@link ISSUE_MARK}. */
const FILE_MARK: Record<string, string> = {
verified: "✓",
mismatch: "✗",
unverifiable: "?",
error: "✗",
"read-error": "✗",
};
const FILE_COLOR: Record<string, string> = {
verified: "green",
mismatch: "red",
unverifiable: "yellow",
error: "red",
"read-error": "red",
};
/** The file name a manifest URI ends in, for a list that must fit 40 columns. */
function fileNameOf(uri: string): string {
const cut = uri.lastIndexOf("/");
return cut === -1 ? uri : uri.slice(cut + 1);
}
/**
* The Skills pane (SEP-2640, #2248): the catalog on the left, and on the right
* the selected skill's frontmatter, its conformance findings, and its manifest.
*
* **Enter verifies.** The static checks run on every render — they are a pure
* walk over a list already in memory — but digest verification needs the bytes,
* so it is one `resources/read` per manifest entry and must be asked for. That
* split is the same one the web screen makes and the same one SEP-2640 makes:
* hosts MUST NOT retrieve a skill's files ahead of need.
*/
export function SkillsTab({
skills,
pageCount,
loadError = null,
inspectorClient,
width,
height,
focusedPane = null,
onAuthRecoveryRequired,
modalOpen = false,
}: SkillsTabProps) {
const visibleCount = Math.max(1, height - 7);
const { selectedIndex, firstVisible, setSelection } = useSelectableList(
skills.length,
visibleCount,
{ resetWhen: skills },
);
const [error, setError] = useState<string | null>(null);
const [verifying, setVerifying] = useState(false);
/**
* The last verification, keyed by the skill URI it was run for. Keyed rather
* than cleared on selection change so moving off a skill and back does not
* silently discard a verdict the user just paid a round trip for — and keyed
* by URI rather than index so a refresh that reorders the list cannot show
* one skill's verdict under another's name.
*/
const [report, setReport] = useState<{
uri: string;
result: SkillVerifyReport;
} | null>(null);
const scrollViewRef = useRef<ScrollViewRef>(null);
const selectedSkill = skills[selectedIndex] ?? null;
const runVerify = useCallback(
(skill: SkillEntry) => {
if (!inspectorClient || verifying) return;
setVerifying(true);
setError(null);
// The IIFE catches everything it can throw, so there is no rejection for
// this key handler — which cannot await — to own.
void (async () => {
try {
const [result] = await verifySkills(inspectorClient, [skill]);
setReport({ uri: skill.uri, result });
} catch (err) {
if (err instanceof AuthRecoveryRequiredError) {
onAuthRecoveryRequired?.(err);
return;
}
/* v8 ignore start -- `verifySkills` records an ordinary read failure
against the file it happened on and keeps walking, and it re-throws
exactly one error, handled directly above. So nothing the call
graph can produce reaches here; this is the guard that keeps a
future change from becoming an unhandled rejection instead of a
visible message. Exercising it would mean faking a throw the walk
cannot make, which tests the fake rather than the code. */
setError(
err instanceof Error ? err.message : "Failed to verify skill",
);
/* v8 ignore stop */
} finally {
setVerifying(false);
}
})();
},
[inspectorClient, onAuthRecoveryRequired, verifying],
);
useInput(
(input: string, key: Key) => {
if (key.return && selectedSkill && inspectorClient) {
runVerify(selectedSkill);
return;
}
if (focusedPane === "list") {
if (key.upArrow && selectedIndex > 0) {
setSelection(selectedIndex - 1);
} else if (key.downArrow && selectedIndex < skills.length - 1) {
setSelection(selectedIndex + 1);
}
return;
}
if (focusedPane === "details") {
if (key.upArrow) {
scrollViewRef.current?.scrollBy(-1);
} else if (key.downArrow) {
scrollViewRef.current?.scrollBy(1);
} else if (key.pageUp) {
const viewportHeight =
scrollViewRef.current?.getViewportHeight() || 1;
scrollViewRef.current?.scrollBy(-viewportHeight);
} else if (key.pageDown) {
const viewportHeight =
scrollViewRef.current?.getViewportHeight() || 1;
scrollViewRef.current?.scrollBy(viewportHeight);
}
}
},
{
isActive:
!modalOpen && (focusedPane === "list" || focusedPane === "details"),
},
);
// Reset scroll when selection changes. A genuine synchronization with an
// external system (the ScrollView's imperative handle), not state derived
// from a prop — so an effect is the right tool here.
useEffect(() => {
scrollViewRef.current?.scrollTo(0);
}, [selectedIndex]);
const listWidth = Math.floor(width * 0.4);
const detailWidth = width - listWidth;
const issues = selectedSkill ? checkSkillConformance(selectedSkill) : [];
const activeReport =
selectedSkill && report?.uri === selectedSkill.uri ? report.result : null;
const manifest =
selectedSkill && selectedSkill.resources !== DYNAMIC_RESOURCES
? selectedSkill.resources
: [];
return (
<Box flexDirection="row" width={width} height={height}>
<Box
width={listWidth}
height={height}
borderStyle="single"
borderTop={false}
borderBottom={false}
borderLeft={false}
borderRight={true}
flexDirection="column"
paddingX={1}
>
<Box paddingY={1}>
<Text
bold
backgroundColor={focusedPane === "list" ? "yellow" : undefined}
>
Skills ({skills.length}
{pageCount > 1 ? `, ${pageCount} pages` : ""})
</Text>
</Box>
{loadError ? (
<Box paddingY={1}>
<Text color="red">{loadError.message}</Text>
</Box>
) : skills.length === 0 ? (
<Box paddingY={1}>
<Text dimColor>No skills available</Text>
</Box>
) : (
<Box
flexDirection="column"
height={visibleCount}
overflow="hidden"
flexShrink={0}
>
{skills
.slice(firstVisible, firstVisible + visibleCount)
.map((skill, i) => {
const index = firstVisible + i;
const isSelected = index === selectedIndex;
// The per-row mark is the static conformance verdict, which
// costs nothing — it is what makes a bad skill visible in the
// list rather than only after selecting it.
const rowIssues = checkSkillConformance(skill);
const worst = rowIssues.some((it) => it.severity === "error")
? "error"
: rowIssues.length > 0
? "warning"
: null;
return (
<Box key={skill.uri || index} paddingY={0} flexShrink={0}>
<Text>
{isSelected ? "▶ " : " "}
{worst ? (
<Text color={ISSUE_COLOR[worst]}>
{ISSUE_MARK[worst]}{" "}
</Text>
) : (
<Text color="green">✓ </Text>
)}
{skillDisplayName(skill)}
</Text>
</Box>
);
})}
</Box>
)}
</Box>
<Box
width={detailWidth}
height={height}
paddingX={1}
flexDirection="column"
overflow="hidden"
>
{selectedSkill ? (
<>
<Box flexShrink={0} paddingTop={1}>
<Text
bold
backgroundColor={
focusedPane === "details" ? "yellow" : undefined
}
{...(focusedPane === "details" ? {} : { color: "cyan" })}
>
{skillDisplayName(selectedSkill)}
</Text>
</Box>
<ScrollView ref={scrollViewRef} height={height - 5}>
<Box marginTop={1} flexShrink={0}>
<Text dimColor>{selectedSkill.uri}</Text>
</Box>
{selectedSkill.frontmatter.description && (
<Box marginTop={1} flexShrink={0}>
<Text dimColor>{selectedSkill.frontmatter.description}</Text>
</Box>
)}
<Box marginTop={1} flexShrink={0}>
<Text bold>
Conformance{issues.length === 0 ? ": conforms" : ":"}
</Text>
</Box>
{issues.map((issue, idx) => (
<Box key={`issue-${idx}`} paddingLeft={2} flexShrink={0}>
<Text color={ISSUE_COLOR[issue.severity]}>
{ISSUE_MARK[issue.severity]} {issue.message}
</Text>
</Box>
))}
<Box marginTop={1} flexShrink={0}>
<Text bold>
Manifest
{selectedSkill.resources === DYNAMIC_RESOURCES
? ': "dynamic" — no files advertised'
: ` (${manifest.length})`}
</Text>
</Box>
{manifest.map((resource, idx) => {
const fileReport = activeReport?.files.find(
(file) => file.uri === resource.uri,
);
return (
<Box
key={`file-${idx}`}
paddingLeft={2}
flexShrink={0}
flexDirection="column"
>
<Text>
{fileReport ? (
<Text color={FILE_COLOR[fileReport.status] ?? "white"}>
{FILE_MARK[fileReport.status] ?? "?"}{" "}
</Text>
) : (
<Text dimColor>· </Text>
)}
{fileNameOf(resource.uri)}
{resource.size !== undefined ? (
<Text dimColor> ({resource.size} B)</Text>
) : null}
</Text>
{fileReport?.reason && (
<Box paddingLeft={4} flexShrink={0}>
<Text color="red">{fileReport.reason}</Text>
</Box>
)}
</Box>
);
})}
{activeReport && activeReport.frontmatter.length > 0 && (
<>
<Box marginTop={1} flexShrink={0}>
<Text bold>Frontmatter cross-check:</Text>
</Box>
{activeReport.frontmatter.map((issue, idx) => (
<Box key={`fm-${idx}`} paddingLeft={2} flexShrink={0}>
<Text color={ISSUE_COLOR[issue.severity]}>
{ISSUE_MARK[issue.severity]} {issue.message}
</Text>
</Box>
))}
</>
)}
{error && (
<Box marginTop={1} flexShrink={0}>
<Text color="red">{error}</Text>
</Box>
)}
<Box marginTop={1} flexShrink={0}>
<Text dimColor>
{verifying
? "[Verifying…]"
: activeReport
? activeReport.ok
? "[Verified — Enter to re-verify]"
: "[Verification FAILED — Enter to re-verify]"
: "[Enter to verify digests and frontmatter]"}
</Text>
</Box>
</ScrollView>
{focusedPane === "details" && (
<Box
flexShrink={0}
height={1}
justifyContent="center"
backgroundColor="gray"
>
<Text bold color="white">
↑/↓ to scroll, Enter to verify
</Text>
</Box>
)}
</>
) : (
<Box paddingY={1} flexShrink={0}>
<Text dimColor>Select a skill to view details</Text>
</Box>
)}
</Box>
</Box>
);
}

View file

@ -30,6 +30,7 @@ interface TabsProps {
auth?: number;
resources?: number;
prompts?: number;
skills?: number;
tools?: number;
messages?: number;
requests?: number;
@ -39,6 +40,13 @@ interface TabsProps {
showAuth?: boolean;
showLogging?: boolean;
showRequests?: boolean;
/**
* The Skills tab is shown only when the connected server declared the
* SEP-2640 Skills extension — unlike Auth/Logging/Requests, which key off the
* transport, this one keys off a *server* declaration, so it can only be
* known after connecting.
*/
showSkills?: boolean;
}
export function Tabs({
@ -49,6 +57,7 @@ export function Tabs({
showAuth = true,
showLogging = true,
showRequests = false,
showSkills = false,
}: TabsProps) {
let visibleTabs = tabs;
if (!showAuth) {
@ -60,6 +69,9 @@ export function Tabs({
if (!showRequests) {
visibleTabs = visibleTabs.filter((tab) => tab.id !== "requests");
}
if (!showSkills) {
visibleTabs = visibleTabs.filter((tab) => tab.id !== "skills");
}
return (
<Box

View file

@ -3,6 +3,7 @@ export type TabType =
| "auth"
| "resources"
| "prompts"
| "skills"
| "tools"
| "messages"
| "requests"
@ -23,6 +24,11 @@ export const tabs: { id: TabType; label: string; accelerator: string }[] = [
{ id: "auth", label: "Auth", accelerator: "a" },
{ id: "resources", label: "Resources", accelerator: "r" },
{ id: "prompts", label: "Prompts", accelerator: "m" },
// `k`, not `s`: `s` is not in conflict today, but the accelerator has to
// appear in the label and be unique, and `S`kills against a future `S`ampling
// or `S`ettings is the collision this rule anticipates. `k` is the earliest
// remaining letter in the word after `s` and `i` (Info).
{ id: "skills", label: "Skills", accelerator: "k" },
{ id: "tools", label: "Tools", accelerator: "t" },
{ id: "messages", label: "Protocol", accelerator: "p" },
{ id: "requests", label: "Network", accelerator: "n" },