@sammorrowdrums/mcpi-ext 0.2.1 → 1.0.0

package/dist/skills/sep2640/client.js

@@ -0,0 +1,160 @@
+import { SkillValidationError, validateSkillEntry, } from "./protocol.js";
+import { HONOURED_CACHE_SCOPES, MAX_CACHE_TTL_MS, MAX_SKILL_LIST_PAGES } from "./spec.js";
+/**
+ * A client for the draft SEP-2640 skills extension.
+ *
+ * Every request goes through {@link McpPolicy}, which re-checks the negotiated
+ * capability immediately before dispatch. This class therefore never caches
+ * "server X supports skills" — it caches only listing *content*, and only when
+ * the server asked it to with terms this host is willing to honour.
+ */
+export class SkillsExtensionClient {
+    policy;
+    now;
+    listCache = new Map();
+    constructor(options) {
+        this.policy = options.policy;
+        this.now = options.now ?? (() => Date.now());
+    }
+    /** True when the server declared the extension on the live connection. */
+    supports(serverName) {
+        return this.policy.getSkillsExtension(serverName) !== undefined;
+    }
+    /** True when the server additionally declared `directoryRead: true`. */
+    supportsDirectoryRead(serverName) {
+        return this.policy.supportsSkillDirectoryRead(serverName);
+    }
+    /** The declared extension settings, for diagnostics. */
+    capability(serverName) {
+        return this.policy.getSkillsExtension(serverName);
+    }
+    /**
+     * Walk `skills/list` to completion, validating each entry before it is
+     * admitted.
+     *
+     * Pagination stops at {@link MAX_SKILL_LIST_PAGES}; the result is then marked
+     * `truncated` rather than presented as the whole set. A server that returns
+     * the same cursor twice is also treated as truncated, which stops a cursor
+     * loop from becoming an unbounded request stream.
+     */
+    async listSkills(serverName, signal) {
+        const cached = this.readCache(serverName);
+        if (cached)
+            return cached;
+        const skills = [];
+        const rejected = [];
+        const seenCursors = new Set();
+        let cursor;
+        let pages = 0;
+        let truncated = false;
+        let ttlMs;
+        let cacheScope;
+        for (;;) {
+            const result = await this.policy.listMcpSkills(serverName, cursor, signal);
+            pages += 1;
+            for (const entry of result.skills) {
+                try {
+                    validateSkillEntry(entry);
+                    skills.push(entry);
+                }
+                catch (error) {
+                    if (!(error instanceof SkillValidationError))
+                        throw error;
+                    rejected.push({ uri: entry.uri, reason: error.message });
+                }
+            }
+            // Freshness hints from the first page govern the whole listing; a later
+            // page cannot extend the lifetime of data already collected.
+            if (pages === 1) {
+                ttlMs = result.ttlMs;
+                cacheScope = result.cacheScope;
+            }
+            const next = result.nextCursor;
+            if (!next)
+                break;
+            if (seenCursors.has(next) || pages >= MAX_SKILL_LIST_PAGES) {
+                truncated = true;
+                break;
+            }
+            seenCursors.add(next);
+            cursor = next;
+        }
+        const listing = { skills, rejected, truncated, fromCache: false };
+        this.writeCache(serverName, listing, ttlMs, cacheScope);
+        return listing;
+    }
+    /**
+     * Fetch one skill's authoritative entry with `skills/get`.
+     *
+     * Always goes to the server: `skills/get` is what re-establishes current
+     * digests after a verification failure, so serving it from cache would defeat
+     * the recovery path the spec defines.
+     */
+    async getSkill(serverName, uri, signal) {
+        const result = await this.policy.getMcpSkill(serverName, uri, signal);
+        validateSkillEntry(result.skill);
+        return result.skill;
+    }
+    /**
+     * Enumerate a skill directory, when the server declared `directoryRead`.
+     *
+     * Directory listings are navigational only. Nothing they return becomes
+     * readable: a file is readable because the skill entry lists it with a
+     * digest, and a directory cannot add entries to that list.
+     */
+    async readDirectory(serverName, uri, signal) {
+        const resources = [];
+        const seenCursors = new Set();
+        let cursor;
+        let pages = 0;
+        for (;;) {
+            const result = await this.policy.readSkillDirectory(serverName, uri, cursor, signal);
+            pages += 1;
+            resources.push(...result.resources);
+            const next = result.nextCursor;
+            if (!next || seenCursors.has(next) || pages >= MAX_SKILL_LIST_PAGES)
+                break;
+            seenCursors.add(next);
+            cursor = next;
+        }
+        return resources;
+    }
+    /** Drop cached listings; call on disconnect or reset. */
+    clearCache(serverName) {
+        if (serverName === undefined) {
+            this.listCache.clear();
+            return;
+        }
+        this.listCache.delete(serverName);
+    }
+    readCache(serverName) {
+        const entry = this.listCache.get(serverName);
+        if (!entry)
+            return undefined;
+        if (entry.expiresAt <= this.now()) {
+            this.listCache.delete(serverName);
+            return undefined;
+        }
+        return { ...entry.listing, fromCache: true };
+    }
+    /**
+     * Cache a listing only when the server asked for it in terms this host
+     * understands.
+     *
+     * `cacheScope`'s value set is defined by SEP-2549, not SEP-2640, so an
+     * unrecognised scope is treated as "do not cache" rather than guessed at. A
+     * truncated listing is never cached, because caching an incomplete answer is
+     * exactly the "empty listing means no skills" mistake the spec warns against,
+     * just with a longer lifetime.
+     */
+    writeCache(serverName, listing, ttlMs, cacheScope) {
+        if (listing.truncated)
+            return;
+        if (typeof ttlMs !== "number" || !Number.isFinite(ttlMs) || ttlMs <= 0)
+            return;
+        if (cacheScope === undefined || !HONOURED_CACHE_SCOPES.has(cacheScope))
+            return;
+        const lifetime = Math.min(ttlMs, MAX_CACHE_TTL_MS);
+        this.listCache.set(serverName, { listing, expiresAt: this.now() + lifetime });
+    }
+}

package/dist/skills/sep2640/discover.d.ts

@@ -0,0 +1,33 @@
+import type { McpPolicy } from "../../mcp/policy.js";
+import type { McpSkillMetadata } from "../skill-registry.js";
+import type { SkillsExtensionClient } from "./client.js";
+/** Outcome of a SEP-2640 discovery pass against one server. */
+export interface Sep2640DiscoveryResult {
+    readonly skills: McpSkillMetadata[];
+    /** Entries the server offered that this host refused, with the reason. */
+    readonly rejected: {
+        readonly uri: string;
+        readonly reason: string;
+    }[];
+    /** True when the listing was cut short and is known to be incomplete. */
+    readonly truncated: boolean;
+    /** True when the listing was served from the freshness cache. */
+    readonly fromCache: boolean;
+}
+/**
+ * Discover skills from a server that declared the draft skills extension.
+ *
+ * This reads nothing. `skills/list` already carries each skill's frontmatter
+ * verbatim, so name, description and gated tools are all available without
+ * touching SKILL.md — which is precisely what lets this honour the spec's ban
+ * on prefetching. The first byte of skill content is fetched at load time, and
+ * only then.
+ *
+ * Each accepted entry's resource set is registered with the policy, which is
+ * what later authorises reads: a file is readable because this entry listed it,
+ * not because it happens to share a URI prefix.
+ *
+ * An empty result means "the server listed nothing right now". It is not proof
+ * that the server has no skills, and callers must not cache it as such.
+ */
+export declare function discoverSkillsViaExtension(policy: McpPolicy, client: SkillsExtensionClient, serverName: string, log?: (msg: string) => void, signal?: AbortSignal): Promise<Sep2640DiscoveryResult>;

package/dist/skills/sep2640/discover.js

@@ -0,0 +1,82 @@
+import { frontmatterDescription, frontmatterName, resourceSetFingerprint, } from "./protocol.js";
+/**
+ * Discover skills from a server that declared the draft skills extension.
+ *
+ * This reads nothing. `skills/list` already carries each skill's frontmatter
+ * verbatim, so name, description and gated tools are all available without
+ * touching SKILL.md — which is precisely what lets this honour the spec's ban
+ * on prefetching. The first byte of skill content is fetched at load time, and
+ * only then.
+ *
+ * Each accepted entry's resource set is registered with the policy, which is
+ * what later authorises reads: a file is readable because this entry listed it,
+ * not because it happens to share a URI prefix.
+ *
+ * An empty result means "the server listed nothing right now". It is not proof
+ * that the server has no skills, and callers must not cache it as such.
+ */
+export async function discoverSkillsViaExtension(policy, client, serverName, log = console.error, signal) {
+    const listing = await client.listSkills(serverName, signal);
+    const skills = [];
+    const rejected = [...listing.rejected];
+    for (const entry of listing.skills) {
+        const name = frontmatterName(entry);
+        if (!name) {
+            rejected.push({ uri: entry.uri, reason: "frontmatter is missing a name" });
+            continue;
+        }
+        const fingerprint = resourceSetFingerprint(entry);
+        policy.registerSkillResources(serverName, entry.uri, listedResourceUris(entry));
+        skills.push({
+            name,
+            description: frontmatterDescription(entry) ?? "",
+            uri: entry.uri,
+            serverName,
+            allowedTools: parseAllowedTools(entry.frontmatter),
+            origin: "sep2640",
+            contentFingerprint: fingerprint,
+        });
+    }
+    for (const failure of rejected) {
+        log(`[skills] Rejected skill ${failure.uri} from "${serverName}": ${failure.reason}`);
+    }
+    if (listing.truncated) {
+        log(`[skills] Listing from "${serverName}" was truncated; this is a partial view, not the full skill set`);
+    }
+    skills.sort((left, right) => (left.name < right.name ? -1 : left.name > right.name ? 1 : 0));
+    return { skills, rejected, truncated: listing.truncated, fromCache: listing.fromCache };
+}
+/**
+ * URIs this entry authorises for reading.
+ *
+ * A `"dynamic"` resource set authorises nothing up front — the policy's
+ * allowlist stays empty and reads are refused. Dynamic skills are readable only
+ * through an explicit per-read decision, which is the honest reading of a
+ * server declining to say what its skill contains.
+ */
+function listedResourceUris(entry) {
+    if (entry.resources === "dynamic")
+        return [];
+    return entry.resources.map((ref) => ref.uri);
+}
+/**
+ * Read `allowed-tools` from verbatim SEP-2640 frontmatter.
+ *
+ * Only the spec-defined `allowed-tools` key is honoured here. The extension
+ * reserves the `io.modelcontextprotocol/` metadata prefix but defines no keys
+ * under it, so the legacy path's `io.modelcontextprotocol/tools` lookup is not
+ * repeated on this contract.
+ *
+ * These names stay inert until the user approves the grant: parsing them is not
+ * activating them.
+ */
+function parseAllowedTools(frontmatter) {
+    const declared = frontmatter["allowed-tools"];
+    if (Array.isArray(declared)) {
+        return declared.filter((value) => typeof value === "string");
+    }
+    if (typeof declared === "string" && declared.trim().length > 0) {
+        return declared.trim().split(/\s+/);
+    }
+    return [];
+}

package/dist/skills/sep2640/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Client for the **draft** MCP skills extension, SEP-2640.
+ *
+ * This is an unratified proposal. See {@link ./spec.ts} for the exact revision
+ * this code was written against, and `docs/skills.md` for the negotiation,
+ * integrity and fallback model.
+ */
+export { DIRECTORY_MIME_TYPE, HONOURED_CACHE_SCOPES, MAX_CACHE_TTL_MS, MAX_SKILL_LIST_PAGES, MAX_SKILL_RESOURCE_ENTRIES, MAX_SKILL_TOTAL_BYTES, SKILL_DIGEST_PATTERN, SKILLS_EXTENSION_NAME, SKILLS_EXTENSION_REVISION, SKILLS_EXTENSION_STATUS, SKILLS_METHODS, describeNegotiation, skillsExtensionDiagnostic, } from "./spec.js";
+export { declaredTotalBytes, DirectoryReadResultSchema, DirectoryResourceSchema, finalPathSegment, findResourceRef, frontmatterDescription, frontmatterName, isDirectoryResource, isValidDigest, resourceSetFingerprint, SkillEntrySchema, SkillResourceRefSchema, SkillsGetResultSchema, SkillsListResultSchema, skillPathOf, SkillValidationError, validateSkillEntry, type DirectoryReadResult, type DirectoryResource, type SkillEntry, type SkillResourceRef, type SkillsGetResult, type SkillsListResult, type SkillValidationCode, } from "./protocol.js";
+export { base64ToBytes, computeDigest, SkillIntegrityError, textToBytes, verifyBytes, verifyFrontmatter, verifyNamePath, verifyResourceRead, type IntegrityFailureCode, } from "./integrity.js";
+export { SkillsExtensionClient, type SkillsExtensionClientOptions, type SkillsListing, } from "./client.js";
+export { discoverSkillsViaExtension, type Sep2640DiscoveryResult } from "./discover.js";
+export { loadSkillDocument, readSkillResource, SkillFetchBudget, type ReadSkillResourceOptions, type VerifiedResource, } from "./load.js";

package/dist/skills/sep2640/index.js

@@ -0,0 +1,13 @@
+/**
+ * Client for the **draft** MCP skills extension, SEP-2640.
+ *
+ * This is an unratified proposal. See {@link ./spec.ts} for the exact revision
+ * this code was written against, and `docs/skills.md` for the negotiation,
+ * integrity and fallback model.
+ */
+export { DIRECTORY_MIME_TYPE, HONOURED_CACHE_SCOPES, MAX_CACHE_TTL_MS, MAX_SKILL_LIST_PAGES, MAX_SKILL_RESOURCE_ENTRIES, MAX_SKILL_TOTAL_BYTES, SKILL_DIGEST_PATTERN, SKILLS_EXTENSION_NAME, SKILLS_EXTENSION_REVISION, SKILLS_EXTENSION_STATUS, SKILLS_METHODS, describeNegotiation, skillsExtensionDiagnostic, } from "./spec.js";
+export { declaredTotalBytes, DirectoryReadResultSchema, DirectoryResourceSchema, finalPathSegment, findResourceRef, frontmatterDescription, frontmatterName, isDirectoryResource, isValidDigest, resourceSetFingerprint, SkillEntrySchema, SkillResourceRefSchema, SkillsGetResultSchema, SkillsListResultSchema, skillPathOf, SkillValidationError, validateSkillEntry, } from "./protocol.js";
+export { base64ToBytes, computeDigest, SkillIntegrityError, textToBytes, verifyBytes, verifyFrontmatter, verifyNamePath, verifyResourceRead, } from "./integrity.js";
+export { SkillsExtensionClient, } from "./client.js";
+export { discoverSkillsViaExtension } from "./discover.js";
+export { loadSkillDocument, readSkillResource, SkillFetchBudget, } from "./load.js";

package/dist/skills/sep2640/integrity.d.ts

@@ -0,0 +1,58 @@
+import { type SkillEntry, type SkillResourceRef } from "./protocol.js";
+export type IntegrityFailureCode = "resource_not_listed" | "size_mismatch" | "digest_mismatch" | "malformed_digest" | "frontmatter_mismatch" | "name_path_mismatch" | "dynamic_budget_exceeded" | "no_text_content";
+/** A refusal to use retrieved content. Distinct from a transport or policy error. */
+export declare class SkillIntegrityError extends Error {
+    readonly code: IntegrityFailureCode;
+    readonly uri: string;
+    constructor(code: IntegrityFailureCode, message: string, uri: string);
+}
+/** SHA-256 over raw bytes, formatted the way SEP-2640 writes digests. */
+export declare function computeDigest(bytes: Uint8Array): string;
+/**
+ * The exact bytes a digest covers.
+ *
+ * MCP text resources arrive as a JS string; the digest is over the file's raw
+ * bytes, so the string is encoded back to UTF-8 — the encoding MCP uses on the
+ * wire — before hashing. Binary resources arrive base64-encoded and are decoded
+ * instead. Getting this wrong would make every digest comparison meaningless,
+ * which is why it is one function used by every caller.
+ */
+export declare function textToBytes(text: string): Uint8Array;
+export declare function base64ToBytes(data: string): Uint8Array;
+/**
+ * Verify retrieved bytes against a declared resource reference.
+ *
+ * Size is checked first and treated as a verification failure in its own right,
+ * exactly like a digest mismatch — a wrong length already proves the bytes are
+ * not the declared file, and saying so names the cheaper, more legible failure.
+ */
+export declare function verifyBytes(ref: SkillResourceRef, bytes: Uint8Array): void;
+/**
+ * Authorize and verify one retrieved file against its skill entry.
+ *
+ * A URI absent from the entry's `resources` is a verification failure, not a
+ * permissive default: SEP-2640 requires reads to resolve only to listed URIs,
+ * so an unlisted file is refused even though the server volunteered it.
+ *
+ * For `"dynamic"` sets there is nothing to compare against, so the only
+ * enforceable constraint is the 16 MiB ceiling applied to what is actually
+ * retrieved. `retrievedBytesSoFar` carries the running total for the skill.
+ */
+export declare function verifyResourceRead(entry: SkillEntry, uri: string, bytes: Uint8Array, retrievedBytesSoFar?: number): void;
+/**
+ * Reparse SKILL.md's own frontmatter and compare it field-by-field with the
+ * listing's `frontmatter`.
+ *
+ * The listing and the file are two independent claims about the same thing;
+ * this is what stops a server advertising a benign description and a benign
+ * tool grant while shipping a file that says something else. Comparison is
+ * exact and symmetric — a field present in one and absent from the other is a
+ * mismatch, and so is a differing value.
+ */
+export declare function verifyFrontmatter(entry: SkillEntry, skillMarkdown: string): void;
+/**
+ * Re-check the name/path agreement against the *parsed file*, not just the
+ * listing. `validateSkillEntry` already checked the listing's copy; this closes
+ * the case where the two disagree about which one the path is supposed to match.
+ */
+export declare function verifyNamePath(entry: SkillEntry): void;

package/dist/skills/sep2640/integrity.js

@@ -0,0 +1,185 @@
+/**
+ * SEP-2640 content verification.
+ *
+ * Everything a server hands back crosses this module before it is used. The
+ * proposal is explicit that digests are *not* a security boundary — the same
+ * party authors both the listing and the content, so a digest proves only that
+ * the two agree. That is still worth enforcing: it is what makes silent
+ * substitution, truncation, and listing/content drift detectable, and it is what
+ * lets an approval be bound to exact bytes rather than to a name.
+ *
+ * Three independent checks apply to every retrieved file:
+ *   1. byte length equals the declared `size`;
+ *   2. SHA-256 over the raw bytes equals the declared `digest`;
+ *   3. for SKILL.md only, the frontmatter reparsed from those bytes matches the
+ *      listing's `frontmatter` field-by-field.
+ *
+ * A failure in any of them means the content MUST NOT be used.
+ */
+import { parseFrontmatter } from "@sammorrowdrums/mcpi";
+import { createHash } from "node:crypto";
+import { findResourceRef, frontmatterName, isValidDigest, skillPathOf, finalPathSegment, } from "./protocol.js";
+import { MAX_SKILL_TOTAL_BYTES } from "./spec.js";
+/** A refusal to use retrieved content. Distinct from a transport or policy error. */
+export class SkillIntegrityError extends Error {
+    code;
+    uri;
+    constructor(code, message, uri) {
+        super(message);
+        this.name = "SkillIntegrityError";
+        this.code = code;
+        this.uri = uri;
+    }
+}
+/** SHA-256 over raw bytes, formatted the way SEP-2640 writes digests. */
+export function computeDigest(bytes) {
+    return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+/**
+ * The exact bytes a digest covers.
+ *
+ * MCP text resources arrive as a JS string; the digest is over the file's raw
+ * bytes, so the string is encoded back to UTF-8 — the encoding MCP uses on the
+ * wire — before hashing. Binary resources arrive base64-encoded and are decoded
+ * instead. Getting this wrong would make every digest comparison meaningless,
+ * which is why it is one function used by every caller.
+ */
+export function textToBytes(text) {
+    return new Uint8Array(Buffer.from(text, "utf8"));
+}
+export function base64ToBytes(data) {
+    return new Uint8Array(Buffer.from(data, "base64"));
+}
+/**
+ * Verify retrieved bytes against a declared resource reference.
+ *
+ * Size is checked first and treated as a verification failure in its own right,
+ * exactly like a digest mismatch — a wrong length already proves the bytes are
+ * not the declared file, and saying so names the cheaper, more legible failure.
+ */
+export function verifyBytes(ref, bytes) {
+    if (!isValidDigest(ref.digest)) {
+        throw new SkillIntegrityError("malformed_digest", `Resource ${ref.uri} declares a non-conforming digest "${ref.digest}"; content was discarded unverified.`, ref.uri);
+    }
+    if (bytes.byteLength !== ref.size) {
+        throw new SkillIntegrityError("size_mismatch", `Resource ${ref.uri} was declared as ${ref.size} bytes but ${bytes.byteLength} bytes were returned. ` +
+            `The content does not match the listing and was discarded.`, ref.uri);
+    }
+    const actual = computeDigest(bytes);
+    if (actual !== ref.digest) {
+        throw new SkillIntegrityError("digest_mismatch", `Resource ${ref.uri} hashed to ${actual} but the listing declared ${ref.digest}. ` +
+            `The content does not match the listing and was discarded.`, ref.uri);
+    }
+}
+/**
+ * Authorize and verify one retrieved file against its skill entry.
+ *
+ * A URI absent from the entry's `resources` is a verification failure, not a
+ * permissive default: SEP-2640 requires reads to resolve only to listed URIs,
+ * so an unlisted file is refused even though the server volunteered it.
+ *
+ * For `"dynamic"` sets there is nothing to compare against, so the only
+ * enforceable constraint is the 16 MiB ceiling applied to what is actually
+ * retrieved. `retrievedBytesSoFar` carries the running total for the skill.
+ */
+export function verifyResourceRead(entry, uri, bytes, retrievedBytesSoFar = 0) {
+    const ref = findResourceRef(entry, uri);
+    if (ref === undefined) {
+        throw new SkillIntegrityError("resource_not_listed", `Resource ${uri} is not listed in skill ${entry.uri}'s resources, so there is no digest to verify it ` +
+            `against. Reads must resolve only to listed URIs.`, uri);
+    }
+    if (ref === "dynamic") {
+        const total = retrievedBytesSoFar + bytes.byteLength;
+        if (total > MAX_SKILL_TOTAL_BYTES) {
+            throw new SkillIntegrityError("dynamic_budget_exceeded", `Skill ${entry.uri} declares a dynamic resource set and has now retrieved ${total} bytes, above the ` +
+                `SEP-2640 ceiling of ${MAX_SKILL_TOTAL_BYTES} bytes (16 MiB).`, uri);
+        }
+        return;
+    }
+    verifyBytes(ref, bytes);
+}
+/**
+ * Reparse SKILL.md's own frontmatter and compare it field-by-field with the
+ * listing's `frontmatter`.
+ *
+ * The listing and the file are two independent claims about the same thing;
+ * this is what stops a server advertising a benign description and a benign
+ * tool grant while shipping a file that says something else. Comparison is
+ * exact and symmetric — a field present in one and absent from the other is a
+ * mismatch, and so is a differing value.
+ */
+export function verifyFrontmatter(entry, skillMarkdown) {
+    const parsed = parseFrontmatter(skillMarkdown);
+    const actual = parsed.frontmatter;
+    const declared = entry.frontmatter;
+    const keys = new Set([...Object.keys(declared), ...Object.keys(actual)]);
+    const differences = [];
+    for (const key of [...keys].sort()) {
+        const inDeclared = Object.hasOwn(declared, key);
+        const inActual = Object.hasOwn(actual, key);
+        if (!inActual) {
+            differences.push(`"${key}" was advertised in the listing but is absent from SKILL.md`);
+            continue;
+        }
+        if (!inDeclared) {
+            differences.push(`"${key}" is present in SKILL.md but was not advertised in the listing`);
+            continue;
+        }
+        if (!deepEqual(declared[key], actual[key])) {
+            differences.push(`"${key}" differs: listing has ${preview(declared[key])}, SKILL.md has ${preview(actual[key])}`);
+        }
+    }
+    if (differences.length > 0) {
+        throw new SkillIntegrityError("frontmatter_mismatch", `Skill ${entry.uri} was not loaded: its SKILL.md frontmatter does not match the listing. ` +
+            differences.join("; "), entry.uri);
+    }
+}
+/**
+ * Re-check the name/path agreement against the *parsed file*, not just the
+ * listing. `validateSkillEntry` already checked the listing's copy; this closes
+ * the case where the two disagree about which one the path is supposed to match.
+ */
+export function verifyNamePath(entry) {
+    const name = frontmatterName(entry);
+    const skillPath = skillPathOf(entry.uri);
+    if (name === undefined || skillPath === undefined || finalPathSegment(skillPath) !== name) {
+        throw new SkillIntegrityError("name_path_mismatch", `Skill ${entry.uri} does not agree with its declared name "${name ?? "(none)"}".`, entry.uri);
+    }
+}
+function deepEqual(left, right) {
+    if (left === right)
+        return true;
+    if (typeof left !== typeof right)
+        return false;
+    if (left === null || right === null)
+        return false;
+    if (Array.isArray(left) || Array.isArray(right)) {
+        if (!Array.isArray(left) || !Array.isArray(right))
+            return false;
+        if (left.length !== right.length)
+            return false;
+        return left.every((value, index) => deepEqual(value, right[index]));
+    }
+    if (typeof left === "object") {
+        const leftRecord = left;
+        const rightRecord = right;
+        const leftKeys = Object.keys(leftRecord).sort();
+        const rightKeys = Object.keys(rightRecord).sort();
+        if (leftKeys.length !== rightKeys.length)
+            return false;
+        if (!leftKeys.every((key, index) => key === rightKeys[index]))
+            return false;
+        return leftKeys.every((key) => deepEqual(leftRecord[key], rightRecord[key]));
+    }
+    return false;
+}
+function preview(value) {
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = "(unserializable)";
+    }
+    return text.length > 120 ? `${text.slice(0, 120)}…` : text;
+}

package/dist/skills/sep2640/load.d.ts

@@ -0,0 +1,61 @@
+import type { McpPolicy, McpResourceSource } from "../../mcp/policy.js";
+import type { SkillEntry } from "./protocol.js";
+/** A verified read of one resource belonging to a skill. */
+export interface VerifiedResource {
+    readonly uri: string;
+    /** Raw bytes exactly as digested. */
+    readonly bytes: Uint8Array;
+    /** UTF-8 decoding of {@link bytes}, for text resources. */
+    readonly text: string;
+}
+/**
+ * Tracks how many bytes a skill has actually pulled down.
+ *
+ * Only `"dynamic"` skills need this: a declared resource set is bounded before
+ * the first fetch, but a dynamic one can only be bounded by watching what
+ * arrives.
+ */
+export declare class SkillFetchBudget {
+    private retrieved;
+    get bytesRetrieved(): number;
+    add(count: number): void;
+}
+export interface ReadSkillResourceOptions {
+    readonly policy: McpPolicy;
+    readonly entry: SkillEntry;
+    readonly serverName: string;
+    readonly uri: string;
+    readonly budget?: SkillFetchBudget;
+    readonly source?: McpResourceSource;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Read one resource belonging to a skill and verify it before returning it.
+ *
+ * Verification happens on the raw bytes, on every read, with no cached
+ * "already checked this" shortcut — a digest that was right last time says
+ * nothing about the bytes that just arrived.
+ *
+ * Callers receive content only if it verifies. There is deliberately no way to
+ * obtain the unverified bytes.
+ */
+export declare function readSkillResource(options: ReadSkillResourceOptions): Promise<VerifiedResource>;
+/**
+ * Load a skill's SKILL.md and prove it is the document the listing described.
+ *
+ * Three separate checks have to pass, and each catches something the others
+ * cannot: the digest proves the bytes are the advertised bytes, the
+ * field-by-field frontmatter comparison proves the listing did not describe the
+ * skill as one thing while serving another, and the name/path check proves the
+ * skill is not impersonating a different slot in the namespace.
+ *
+ * Returns the full document text; stripping frontmatter is the caller's job,
+ * because verification needs the document exactly as it was digested.
+ */
+export declare function loadSkillDocument(options: {
+    readonly policy: McpPolicy;
+    readonly entry: SkillEntry;
+    readonly serverName: string;
+    readonly budget?: SkillFetchBudget;
+    readonly signal?: AbortSignal;
+}): Promise<VerifiedResource>;