@unbrained/pm-cli 2026.8.26 → 2026.8.28

package/dist/sdk/mcp/apps.js

@@ -0,0 +1,154 @@
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="e6c49c89-781e-59a3-9c19-6a1c40424587")}catch(e){}}();
+import { PM_MCP_ERROR_CODES, PmMcpProtocolError, isMcpRecord, } from "./protocol.js";
+/** Stable MCP Apps extension identifier. */
+export const PM_MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
+/** Stable MCP Apps specification revision implemented by pm. */
+export const PM_MCP_APPS_SPEC_VERSION = "2026-01-26";
+/** Official MIME type for MCP App HTML resources. */
+export const PM_MCP_APP_MIME_TYPE = "text/html;profile=mcp-app";
+/** Server-side MCP Apps capability advertised through discovery. */
+export const PM_MCP_APPS_SERVER_CAPABILITY = Object.freeze({
+    specVersion: PM_MCP_APPS_SPEC_VERSION,
+    mimeTypes: [PM_MCP_APP_MIME_TYPE],
+});
+/**
+ * Resolve whether a request negotiated MCP Apps, rejecting malformed explicit
+ * declarations instead of silently serving a different extension revision.
+ */
+export function hasPmMcpAppsCapability(context) {
+    const extensions = context.clientCapabilities.extensions;
+    if (!isMcpRecord(extensions))
+        return false;
+    const declaration = extensions[PM_MCP_APPS_EXTENSION];
+    if (declaration === undefined)
+        return false;
+    if (!isMcpRecord(declaration)) {
+        throw new PmMcpProtocolError("Invalid MCP Apps client capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, { requiredCapabilities: { extensions: { [PM_MCP_APPS_EXTENSION]: PM_MCP_APPS_SERVER_CAPABILITY } } });
+    }
+    const mimeTypes = declaration.mimeTypes;
+    const specVersion = declaration.specVersion;
+    if (!Array.isArray(mimeTypes) ||
+        !mimeTypes.includes(PM_MCP_APP_MIME_TYPE) ||
+        (specVersion !== undefined && specVersion !== PM_MCP_APPS_SPEC_VERSION)) {
+        throw new PmMcpProtocolError("Unsupported MCP Apps client capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, { requiredCapabilities: { extensions: { [PM_MCP_APPS_EXTENSION]: PM_MCP_APPS_SERVER_CAPABILITY } } });
+    }
+    return true;
+}
+const PRIVATE_APP_RESOURCE_META = {
+    csp: { connectDomains: [], resourceDomains: [], frameDomains: [] },
+    permissions: {},
+    prefersBorder: true,
+};
+/** Canonical optional pm MCP Apps. */
+export const PM_MCP_APP_CONTRACTS = Object.freeze([
+    {
+        id: "context",
+        name: "Context explorer",
+        description: "Inspect bounded project context, provenance, omissions, and token accounting.",
+        toolName: "pm_context",
+        uri: "ui://pm/context.html",
+    },
+    {
+        id: "graph",
+        name: "Relationship graph",
+        description: "Explore typed relationships, explaining paths, and graph-governance evidence.",
+        toolName: "pm_graph",
+        uri: "ui://pm/graph.html",
+    },
+    {
+        id: "plan",
+        name: "Plan and milestone view",
+        description: "Review durable plan steps, dependencies, decisions, discoveries, and validation state.",
+        toolName: "pm_plan",
+        uri: "ui://pm/plan.html",
+    },
+    {
+        id: "assurance",
+        name: "Assurance dashboard",
+        description: "Inspect validation verdicts, evidence, omissions, and actionable recovery paths.",
+        toolName: "pm_validate",
+        uri: "ui://pm/assurance.html",
+    },
+    {
+        id: "operations",
+        name: "Long-operation view",
+        description: "Inspect durable test and operation results without creating a second task store.",
+        toolName: "pm_test",
+        uri: "ui://pm/operations.html",
+    },
+].map((contract) => ({
+    ...contract,
+    toolMeta: {
+        resourceUri: contract.uri,
+        visibility: ["model", "app"],
+    },
+    resourceMeta: PRIVATE_APP_RESOURCE_META,
+})));
+/** Return the app contract for a resource URI. */
+export function findPmMcpAppByUri(uri) {
+    return PM_MCP_APP_CONTRACTS.find((contract) => contract.uri === uri);
+}
+/** Attach negotiated MCP App metadata to matching tool definitions. */
+export function decoratePmMcpToolsWithApps(tools) {
+    const appsByTool = new Map(PM_MCP_APP_CONTRACTS.map((contract) => [contract.toolName, contract]));
+    return tools.map((tool) => {
+        const app = appsByTool.get(tool.name);
+        return app
+            ? {
+                ...tool,
+                _meta: { ...tool._meta, ui: app.toolMeta },
+            }
+            : { ...tool };
+    });
+}
+function escapeHtml(value) {
+    return value
+        .replaceAll("&", "&")
+        .replaceAll("<", "&lt;")
+        .replaceAll(">", "&gt;")
+        .replaceAll('"', "&quot;")
+        .replaceAll("'", "&#39;");
+}
+/**
+ * Render a self-contained, sandbox-compatible MCP App document.
+ *
+ * The view keeps no durable state and exposes no mutation control. It receives
+ * the authoritative tool input/result from the host, bounds large rendering,
+ * and presents the text fallback when structured content is unavailable.
+ */
+export function renderPmMcpAppHtml(contract) {
+    const title = escapeHtml(contract.name);
+    const description = escapeHtml(contract.description);
+    const appInfo = JSON.stringify({
+        name: `pm-${contract.id}-view`,
+        version: PM_MCP_APPS_SPEC_VERSION,
+    });
+    const protocolVersion = JSON.stringify(PM_MCP_APPS_SPEC_VERSION);
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width,initial-scale=1">
+  <title>${title}</title>
+  <style>
+    :root{color-scheme:light dark;--ink:#172554;--muted:#526078;--panel:#f8fafc;--line:#cbd5e1;--signal:#0f766e;--accent:#4338ca;--danger:#b91c1c;font-family:Inter,ui-sans-serif,system-ui,sans-serif}
+    @media(prefers-color-scheme:dark){:root{--ink:#e0e7ff;--muted:#a8b3c7;--panel:#111827;--line:#334155;--signal:#5eead4;--accent:#a5b4fc;--danger:#fca5a5}}
+    *{box-sizing:border-box}body{margin:0;background:var(--panel);color:var(--ink)}main{display:grid;gap:1rem;padding:clamp(.9rem,3vw,1.5rem);max-width:76rem;margin:auto}header{display:grid;gap:.35rem;border-bottom:1px solid var(--line);padding-bottom:.8rem}h1{font-size:clamp(1.2rem,3vw,1.75rem);line-height:1.1;margin:0;letter-spacing:-.02em}p{margin:0;color:var(--muted);line-height:1.5}.status{display:flex;align-items:center;gap:.5rem;font:600 .75rem ui-monospace,monospace;text-transform:uppercase;letter-spacing:.06em}.status::before{content:"";width:.55rem;height:.55rem;border-radius:50%;background:var(--signal)}section{border:1px solid var(--line);border-radius:.8rem;padding:1rem;background:color-mix(in srgb,var(--panel) 92%,var(--accent) 8%)}h2{font-size:.75rem;text-transform:uppercase;letter-spacing:.08em;margin:0 0 .7rem;color:var(--accent)}pre{white-space:pre-wrap;overflow-wrap:anywhere;max-height:34rem;overflow:auto;margin:0;font:500 .78rem/1.55 ui-monospace,SFMono-Regular,monospace;tab-size:2}button{justify-self:start;border:1px solid var(--accent);border-radius:.45rem;background:transparent;color:var(--accent);padding:.55rem .75rem;font:600 .78rem inherit;cursor:pointer}button:focus-visible{outline:3px solid var(--signal);outline-offset:2px}.notice{color:var(--danger)}@media(max-width:40rem){main{padding:.75rem}section{padding:.8rem}pre{max-height:24rem}}@media(prefers-reduced-motion:reduce){*{scroll-behavior:auto!important;transition:none!important}}
+  </style>
+</head>
+<body>
+<main>
+  <header><div class="status" id="status" role="status" aria-live="polite">Connecting to host</div><h1>${title}</h1><p>${description}</p></header>
+  <section aria-labelledby="summary-title"><h2 id="summary-title">Authoritative result</h2><pre id="result" tabindex="0">Waiting for the host tool result…</pre></section>
+  <section aria-labelledby="input-title"><h2 id="input-title">Invocation context</h2><pre id="input" tabindex="0">No tool input received.</pre></section>
+  <button type="button" id="copy">Copy visible evidence</button>
+</main>
+<script>
+(()=>{"use strict";const MAX=24000,status=document.querySelector("#status"),result=document.querySelector("#result"),input=document.querySelector("#input"),pending=new Map();let nextId=1;const render=(node,value)=>{let text;try{text=typeof value==="string"?value:JSON.stringify(value,null,2)}catch{text="Result could not be serialized."}if(text.length>MAX)text=text.slice(0,MAX)+"\\n\\n[View truncated at "+MAX+" characters; use the authoritative pm tool with a cursor or narrower projection.]";node.textContent=text};const send=(message)=>window.parent.postMessage(message,"*");window.addEventListener("message",event=>{if(event.source!==window.parent||!event.data||event.data.jsonrpc!=="2.0")return;const message=event.data;if(message.id!==undefined&&pending.has(message.id)){pending.get(message.id)(message);pending.delete(message.id);return}if(message.method==="ui/notifications/tool-input"||message.method==="ui/notifications/tool-input-partial"){render(input,message.params?.arguments??message.params);status.textContent="Input received"}else if(message.method==="ui/notifications/tool-result"){render(result,message.params);status.textContent="Current tool result"}else if(message.method==="ui/notifications/tool-cancelled"){status.textContent="Tool call cancelled";status.classList.add("notice")}else if(message.method==="ui/notifications/host-context-changed"&&message.params?.theme){document.documentElement.style.colorScheme=message.params.theme}});const request=(method,params)=>new Promise(resolve=>{const id=nextId++;pending.set(id,resolve);send({jsonrpc:"2.0",id,method,params})});document.querySelector("#copy").addEventListener("click",async()=>{const text=result.textContent+"\\n\\n"+input.textContent;try{await navigator.clipboard.writeText(text);status.textContent="Visible evidence copied"}catch{status.textContent="Clipboard permission unavailable";status.classList.add("notice")}});request("ui/initialize",{appInfo:${appInfo},appCapabilities:{},protocolVersion:${protocolVersion}}).then(message=>{if(message.error){status.textContent="Host rejected MCP App initialization";status.classList.add("notice");return}send({jsonrpc:"2.0",method:"ui/notifications/initialized"});status.textContent="Connected — awaiting authoritative result"})})();
+</script>
+</body>
+</html>`;
+}
+//# sourceMappingURL=apps.js.map
+//# debugId=e6c49c89-781e-59a3-9c19-6a1c40424587

package/dist/sdk/mcp/skills.d.ts

@@ -0,0 +1,127 @@
+import { PM_MCP_PROTOCOL_VERSION, type PmMcpRequestContext } from "./protocol.js";
+/** Draft extension identifier proposed by SEP-2640. */
+export declare const PM_MCP_SKILLS_EXTENSION: "io.modelcontextprotocol/skills";
+/** Exact draft proposal revision implemented by pm. */
+export declare const PM_MCP_SKILLS_DRAFT_REVISION: "SEP-2640@a3e147ca2710f68214247aecc729731ee1ae8d03";
+/** Server-side draft capability advertised through discovery. */
+export declare const PM_MCP_SKILLS_SERVER_CAPABILITY: Readonly<{
+    revision: "SEP-2640@a3e147ca2710f68214247aecc729731ee1ae8d03";
+    status: "draft";
+    directoryRead: true;
+}>;
+/** Require exact draft negotiation for a skills method. */
+export declare function assertPmMcpSkillsCapability(context: PmMcpRequestContext, directoryRead?: boolean): void;
+/** Security and context limits applied independently to every skill origin. */
+export declare const PM_MCP_SKILL_LIMITS: Readonly<{
+    maxFilesPerSkill: 512;
+    maxFileBytes: number;
+    maxSkillBytes: number;
+    defaultPageSize: 20;
+    maxPageSize: 100;
+}>;
+/** Origin from which a skill was loaded. */
+export type PmMcpSkillOrigin = "package" | "workspace";
+/** One immutable file advertised by a skill. */
+export interface PmMcpSkillResource {
+    /** Addressable skill resource URI. */
+    uri: string;
+    /** SEP-2640 SHA-256 digest of the exact bytes returned by reads. */
+    digest: string;
+    /** Exact byte length. */
+    size: number;
+}
+/** Discoverable skill descriptor from the current SEP draft. */
+export interface PmMcpSkillDescriptor {
+    /** URI of the skill's mandatory SKILL.md. */
+    uri: string;
+    /** Parsed, verbatim frontmatter object. */
+    frontmatter: Record<string, unknown>;
+    /** Every bounded file in the skill directory. */
+    resources: PmMcpSkillResource[];
+    /** pm-specific compatibility and trust provenance. */
+    _meta: {
+        contractVersion: 1;
+        extensionRevision: typeof PM_MCP_SKILLS_DRAFT_REVISION;
+        origin: PmMcpSkillOrigin;
+        packageVersion: string;
+        protocolVersion: typeof PM_MCP_PROTOCOL_VERSION;
+        trust: "untrusted";
+        estimatedTokens: number;
+    };
+}
+/** Inputs for loading the canonical package skills plus repository overrides. */
+export interface LoadPmMcpSkillsOptions {
+    /** pm package root containing `.agents/skills`. */
+    packageRoot: string;
+    /** Workspace root whose `.agents/skills` override package skills by name. */
+    workspaceRoot?: string;
+    /** Exact package version included in compatibility metadata. */
+    packageVersion: string;
+}
+/** List request inputs with opaque cursor pagination. */
+export interface ListPmMcpSkillsOptions {
+    /** Opaque cursor returned by a previous page. */
+    cursor?: string;
+    /** Requested page size, bounded to 100. */
+    limit?: number;
+}
+/** One deterministic list page. */
+export interface ListPmMcpSkillsResult {
+    /** Skills in lexical URI order. */
+    skills: PmMcpSkillDescriptor[];
+    /** Opaque continuation cursor when more skills exist. */
+    nextCursor?: string;
+    /** Explicit completeness signal. */
+    hasMore: boolean;
+}
+/** Exact read result for one skill resource. */
+export interface ReadPmMcpSkillResourceResult {
+    /** Resource content returned as UTF-8 text or lossless Base64 bytes. */
+    contents: Array<{
+        uri: string;
+        mimeType: "text/markdown" | "text/plain";
+        text: string;
+        _meta: {
+            digest: string;
+            origin: PmMcpSkillOrigin;
+            trust: "untrusted";
+        };
+    } | {
+        uri: string;
+        mimeType: "application/octet-stream";
+        blob: string;
+        _meta: {
+            digest: string;
+            origin: PmMcpSkillOrigin;
+            trust: "untrusted";
+        };
+    }>;
+}
+/** Direct-child directory listing defined by the current SEP draft. */
+export interface ReadPmMcpSkillDirectoryResult {
+    /** Direct child file and directory resources in lexical URI order. */
+    resources: Array<{
+        uri: string;
+        name: string;
+        mimeType: "application/octet-stream" | "inode/directory" | "text/markdown" | "text/plain";
+    }>;
+    /** Opaque continuation cursor when more direct children exist. */
+    nextCursor?: string;
+    /** Explicit completeness signal for this directory page. */
+    hasMore: boolean;
+}
+/** Immutable in-memory registry for one request's package/workspace origins. */
+export declare class PmMcpSkillRegistry {
+    #private;
+    private constructor();
+    /** Load package skills and apply validated workspace overrides by name. */
+    static load(options: LoadPmMcpSkillsOptions): Promise<PmMcpSkillRegistry>;
+    /** List skills in deterministic pages without loading file bodies. */
+    list(options?: ListPmMcpSkillsOptions): ListPmMcpSkillsResult;
+    /** Get one skill descriptor by its SKILL.md URI. */
+    get(uri: string): PmMcpSkillDescriptor;
+    /** Read one digest-bound skill resource without following filesystem links. */
+    read(uri: string): ReadPmMcpSkillResourceResult;
+    /** List one directory's direct children with opaque cursor pagination. */
+    readDirectory(uri: string, options?: ListPmMcpSkillsOptions): ReadPmMcpSkillDirectoryResult;
+}

package/dist/sdk/mcp/skills.js

@@ -0,0 +1,390 @@
+/**
+ * @module sdk/mcp/skills
+ *
+ * Implements pm's draft Skills over MCP registry with bounded filesystem
+ * discovery, per-file digests, origin provenance, pagination, and fail-closed
+ * revision negotiation.
+ */
+
+!function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="5f60bc89-c81b-57ee-a8f2-0d0b18d0af1b")}catch(e){}}();
+import { createHash } from "node:crypto";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { parseDocument } from "yaml";
+import { isFileAbsentError } from "../../core/fs/fs-utils.js";
+import { PM_MCP_ERROR_CODES, PM_MCP_PROTOCOL_VERSION, PmMcpProtocolError, isMcpRecord, } from "./protocol.js";
+/** Draft extension identifier proposed by SEP-2640. */
+export const PM_MCP_SKILLS_EXTENSION = "io.modelcontextprotocol/skills";
+/** Exact draft proposal revision implemented by pm. */
+export const PM_MCP_SKILLS_DRAFT_REVISION = "SEP-2640@a3e147ca2710f68214247aecc729731ee1ae8d03";
+/** Server-side draft capability advertised through discovery. */
+export const PM_MCP_SKILLS_SERVER_CAPABILITY = Object.freeze({
+    revision: PM_MCP_SKILLS_DRAFT_REVISION,
+    status: "draft",
+    directoryRead: true,
+});
+/** Require exact draft negotiation for a skills method. */
+export function assertPmMcpSkillsCapability(context, directoryRead = false) {
+    const extensions = context.clientCapabilities.extensions;
+    const declaration = isMcpRecord(extensions)
+        ? extensions[PM_MCP_SKILLS_EXTENSION]
+        : undefined;
+    if (!isMcpRecord(declaration) ||
+        declaration.revision !== PM_MCP_SKILLS_DRAFT_REVISION ||
+        (directoryRead && declaration.directoryRead !== true)) {
+        throw new PmMcpProtocolError("Missing or incompatible Skills over MCP draft capability", PM_MCP_ERROR_CODES.missingRequiredClientCapability, {
+            requiredCapabilities: {
+                extensions: {
+                    [PM_MCP_SKILLS_EXTENSION]: PM_MCP_SKILLS_SERVER_CAPABILITY,
+                },
+            },
+        });
+    }
+}
+/** Security and context limits applied independently to every skill origin. */
+export const PM_MCP_SKILL_LIMITS = Object.freeze({
+    maxFilesPerSkill: 512,
+    maxFileBytes: 16 * 1024 * 1024,
+    maxSkillBytes: 16 * 1024 * 1024,
+    defaultPageSize: 20,
+    maxPageSize: 100,
+});
+const MAX_MCP_SKILLS_PER_ORIGIN = 100;
+const MAX_MCP_SKILL_ORIGIN_BYTES = 32 * 1024 * 1024;
+const SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const SKILL_PAGE_SIZES = new Set(Array.from({ length: PM_MCP_SKILL_LIMITS.maxPageSize }, (_, index) => index + 1));
+function skillError(message, data) {
+    throw new PmMcpProtocolError(message, -32602, data);
+}
+function skillFileMimeType(name, bytes) {
+    try {
+        new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        return name.endsWith(".md") ? "text/markdown" : "text/plain";
+    }
+    catch {
+        return "application/octet-stream";
+    }
+}
+function parseSkillFrontmatter(content, source) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(content);
+    if (!match)
+        skillError(`Skill ${source} is missing YAML frontmatter.`);
+    const document = parseDocument(match[1], {
+        prettyErrors: false,
+        strict: true,
+        uniqueKeys: true,
+    });
+    if (document.errors.length > 0) {
+        skillError(`Skill ${source} has invalid YAML frontmatter.`, {
+            errors: document.errors.map((error) => error.message),
+        });
+    }
+    let value;
+    try {
+        value = document.toJS({ maxAliasCount: 0 });
+    }
+    catch (error) {
+        skillError(`Skill ${source} has unsupported YAML aliases.`, {
+            error: String(error),
+        });
+    }
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        skillError(`Skill ${source} frontmatter must be an object.`);
+    }
+    return value;
+}
+async function readBoundedSkillFile(filePath, relative, size, budget) {
+    if (size > PM_MCP_SKILL_LIMITS.maxFileBytes) {
+        skillError(`Skill resource exceeds the per-file limit: ${relative}.`);
+    }
+    budget.files += 1;
+    if (budget.files > PM_MCP_SKILL_LIMITS.maxFilesPerSkill) {
+        skillError(`Skill exceeds ${PM_MCP_SKILL_LIMITS.maxFilesPerSkill} files.`);
+    }
+    budget.skillBytes += size;
+    if (budget.skillBytes > PM_MCP_SKILL_LIMITS.maxSkillBytes) {
+        skillError(`Skill exceeds the aggregate byte limit: ${relative}.`);
+    }
+    budget.originBytes.value += size;
+    if (budget.originBytes.value > MAX_MCP_SKILL_ORIGIN_BYTES) {
+        skillError(`Skill origin exceeds the aggregate byte limit: ${relative}.`);
+    }
+    return readFile(filePath);
+}
+async function collectSkillFiles(root, relative, budget) {
+    const directory = path.join(root, relative);
+    const entries = await readdir(directory, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        const childRelative = path.posix.join(relative.split(path.sep).join("/"), entry.name);
+        const childPath = path.join(root, ...childRelative.split("/"));
+        const stats = await lstat(childPath);
+        if (stats.isSymbolicLink()) {
+            skillError(`Skill resource must not be a symbolic link: ${childRelative}.`);
+        }
+        if (stats.isDirectory()) {
+            files.push(...(await collectSkillFiles(root, childRelative, budget)));
+        }
+        else if (stats.isFile()) {
+            files.push({
+                relative: childRelative,
+                bytes: await readBoundedSkillFile(childPath, childRelative, stats.size, budget),
+            });
+        }
+        else {
+            skillError(`Skill resource must be a regular file or directory: ${childRelative}.`);
+        }
+    }
+    return files;
+}
+async function loadSkillOrigin(skillsRoot, origin, packageVersion) {
+    const skills = new Map();
+    let entries;
+    try {
+        entries = await readdir(skillsRoot, { withFileTypes: true });
+    }
+    catch (error) {
+        if (isFileAbsentError(error)) {
+            return skills;
+        }
+        throw error;
+    }
+    const skillEntries = entries
+        .filter((entry) => entry.isDirectory() && SKILL_NAME_PATTERN.test(entry.name))
+        .sort((left, right) => left.name.localeCompare(right.name));
+    if (skillEntries.length > MAX_MCP_SKILLS_PER_ORIGIN) {
+        skillError(`Skill origin exceeds ${MAX_MCP_SKILLS_PER_ORIGIN} directories.`);
+    }
+    const originBytes = { value: 0 };
+    for (const entry of skillEntries) {
+        const files = await collectSkillFiles(path.join(skillsRoot, entry.name), "", {
+            files: 0,
+            skillBytes: 0,
+            originBytes,
+        });
+        const totalBytes = files.reduce((sum, file) => sum + file.bytes.byteLength, 0);
+        const main = files.find((file) => file.relative === "SKILL.md");
+        if (!main)
+            continue;
+        const frontmatter = parseSkillFrontmatter(main.bytes.toString("utf8"), entry.name);
+        if (frontmatter.name !== entry.name) {
+            skillError(`Skill directory ${entry.name} must match frontmatter name.`, {
+                actual: frontmatter.name ?? null,
+                expected: entry.name,
+            });
+        }
+        if (typeof frontmatter.description !== "string" ||
+            frontmatter.description.trim().length === 0) {
+            skillError(`Skill ${entry.name} requires a non-empty frontmatter description.`, {
+                required: ["description"],
+            });
+        }
+        const resources = files.map((file) => ({
+            uri: `skill://${entry.name}/${file.relative}`,
+            digest: `sha256:${createHash("sha256").update(file.bytes).digest("hex")}`,
+            size: file.bytes.byteLength,
+        }));
+        const fingerprint = createHash("sha256")
+            .update(resources
+            .map((resource) => `${resource.uri}:${resource.digest}`)
+            .join("\n"))
+            .digest("hex");
+        skills.set(entry.name, {
+            uri: `skill://${entry.name}/SKILL.md`,
+            frontmatter,
+            resources,
+            _meta: {
+                contractVersion: 1,
+                extensionRevision: PM_MCP_SKILLS_DRAFT_REVISION,
+                origin,
+                packageVersion,
+                protocolVersion: PM_MCP_PROTOCOL_VERSION,
+                trust: "untrusted",
+                estimatedTokens: Math.ceil(totalBytes / 4),
+            },
+            files: new Map(files.map((file) => [file.relative, file.bytes])),
+            fingerprint,
+        });
+    }
+    return skills;
+}
+function projectSkill(skill) {
+    const { files: _files, fingerprint: _fingerprint, ...descriptor } = skill;
+    return descriptor;
+}
+/** Immutable in-memory registry for one request's package/workspace origins. */
+export class PmMcpSkillRegistry {
+    #skills;
+    #fingerprint;
+    constructor(skills) {
+        this.#skills = skills;
+        this.#fingerprint = createHash("sha256")
+            .update([...skills.entries()]
+            .sort(([left], [right]) => left.localeCompare(right))
+            .map(([name, skill]) => `${name}:${skill.fingerprint}`)
+            .join("\n"))
+            .digest("hex")
+            .slice(0, 16);
+    }
+    /** Decode one registry-bound cursor for a list or directory scope. */
+    #decodeCursor(cursor, scope) {
+        if (!cursor)
+            return 0;
+        try {
+            const parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+            if (typeof parsed !== "object" ||
+                parsed === null ||
+                !("fingerprint" in parsed) ||
+                parsed.fingerprint !== this.#fingerprint ||
+                !("scope" in parsed) ||
+                parsed.scope !== scope ||
+                !("offset" in parsed) ||
+                !Number.isInteger(parsed.offset) ||
+                Number(parsed.offset) < 0) {
+                skillError("Skill cursor is invalid or stale.");
+            }
+            return Number(parsed.offset);
+        }
+        catch (error) {
+            if (error instanceof PmMcpProtocolError)
+                throw error;
+            return skillError("Skill cursor is invalid or stale.");
+        }
+    }
+    /** Encode one registry-bound continuation cursor. */
+    #encodeCursor(offset, scope) {
+        return Buffer.from(JSON.stringify({ fingerprint: this.#fingerprint, offset, scope })).toString("base64url");
+    }
+    /** Load package skills and apply validated workspace overrides by name. */
+    static async load(options) {
+        const packaged = await loadSkillOrigin(path.join(options.packageRoot, ".agents", "skills"), "package", options.packageVersion);
+        if (options.workspaceRoot) {
+            const packageSkillsRoot = path.resolve(options.packageRoot, ".agents", "skills");
+            const workspaceSkillsRoot = path.resolve(options.workspaceRoot, ".agents", "skills");
+            if (workspaceSkillsRoot !== packageSkillsRoot) {
+                const overrides = await loadSkillOrigin(workspaceSkillsRoot, "workspace", options.packageVersion);
+                for (const [name, skill] of overrides)
+                    packaged.set(name, skill);
+            }
+        }
+        return new PmMcpSkillRegistry(packaged);
+    }
+    /** List skills in deterministic pages without loading file bodies. */
+    list(options = {}) {
+        const limit = options.limit ?? PM_MCP_SKILL_LIMITS.defaultPageSize;
+        if (!SKILL_PAGE_SIZES.has(limit)) {
+            skillError(`Skill list limit must be an integer from 1 to ${PM_MCP_SKILL_LIMITS.maxPageSize}.`);
+        }
+        const offset = this.#decodeCursor(options.cursor, "skills/list");
+        const ordered = [...this.#skills.values()].sort((left, right) => left.uri.localeCompare(right.uri));
+        const page = ordered.slice(offset, offset + limit);
+        const nextOffset = offset + page.length;
+        const hasMore = nextOffset < ordered.length;
+        return {
+            skills: page.map(projectSkill),
+            hasMore,
+            ...(hasMore
+                ? {
+                    nextCursor: this.#encodeCursor(nextOffset, "skills/list"),
+                }
+                : {}),
+        };
+    }
+    /** Get one skill descriptor by its SKILL.md URI. */
+    get(uri) {
+        const match = /^skill:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)\/SKILL\.md$/u.exec(uri);
+        const skill = match ? this.#skills.get(match[1]) : undefined;
+        if (!skill)
+            skillError(`Unknown pm MCP skill: ${uri}.`, { field: "uri" });
+        return projectSkill(skill);
+    }
+    /** Read one digest-bound skill resource without following filesystem links. */
+    read(uri) {
+        const match = /^skill:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)\/(.+)$/u.exec(uri);
+        const skill = match ? this.#skills.get(match[1]) : undefined;
+        const relative = match?.[2] ?? "";
+        const bytes = skill && relative ? skill.files.get(relative) : undefined;
+        const resource = skill?.resources.find((candidate) => candidate.uri === uri);
+        if (!skill || !bytes || !resource) {
+            skillError(`Unknown pm MCP skill resource: ${uri}.`, { field: "uri" });
+        }
+        const metadata = {
+            digest: resource.digest,
+            origin: skill._meta.origin,
+            trust: "untrusted",
+        };
+        const mimeType = skillFileMimeType(relative, bytes);
+        if (mimeType !== "application/octet-stream") {
+            return {
+                contents: [
+                    {
+                        uri,
+                        mimeType,
+                        text: bytes.toString("utf8"),
+                        _meta: metadata,
+                    },
+                ],
+            };
+        }
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType,
+                    blob: bytes.toString("base64"),
+                    _meta: metadata,
+                },
+            ],
+        };
+    }
+    /** List one directory's direct children with opaque cursor pagination. */
+    readDirectory(uri, options = {}) {
+        const match = /^skill:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)(?:\/(.+))?$/u.exec(uri);
+        const skill = match ? this.#skills.get(match[1]) : undefined;
+        if (!skill)
+            skillError(`Unknown pm MCP skill directory: ${uri}.`, { field: "uri" });
+        const directory = (match?.[2] ?? "").replace(/\/$/u, "");
+        const prefix = directory.length > 0 ? `${directory}/` : "";
+        const base = `skill://${match[1]}`;
+        const children = new Map();
+        for (const resource of skill.resources) {
+            const relative = resource.uri.slice(`${base}/`.length);
+            if (!relative.startsWith(prefix))
+                continue;
+            const remainder = relative.slice(prefix.length);
+            const [name, ...descendants] = remainder.split("/");
+            const childUri = `${base}/${prefix}${name}`;
+            const childBytes = skill.files.get(`${prefix}${name}`);
+            children.set(name, {
+                uri: childUri,
+                name,
+                mimeType: descendants.length > 0
+                    ? "inode/directory"
+                    : skillFileMimeType(name, childBytes),
+            });
+        }
+        if (directory.length > 0 && children.size === 0) {
+            skillError(`Unknown pm MCP skill directory: ${uri}.`, { field: "uri" });
+        }
+        const limit = options.limit ?? PM_MCP_SKILL_LIMITS.maxPageSize;
+        if (!SKILL_PAGE_SIZES.has(limit)) {
+            skillError(`Skill directory limit must be an integer from 1 to ${PM_MCP_SKILL_LIMITS.maxPageSize}.`);
+        }
+        const offset = this.#decodeCursor(options.cursor, uri);
+        const ordered = [...children.values()].sort((left, right) => left.uri.localeCompare(right.uri));
+        const resources = ordered.slice(offset, offset + limit);
+        const nextOffset = offset + resources.length;
+        const hasMore = nextOffset < ordered.length;
+        return {
+            resources,
+            hasMore,
+            ...(hasMore
+                ? {
+                    nextCursor: this.#encodeCursor(nextOffset, uri),
+                }
+                : {}),
+        };
+    }
+}
+//# sourceMappingURL=skills.js.map
+//# debugId=5f60bc89-c81b-57ee-a8f2-0d0b18d0af1b