@unbrained/pm-cli 2026.9.7 → 2026.9.9

package/dist/sdk/mcp/skills.js

@@ -1,390 +1,2 @@
-/**
- * @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),
-                }
-                : {}),
-        };
-    }
-}
+!(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]="6bfbe073-3869-5451-9d65-499960a28af9")}catch(e2){}})();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";const PM_MCP_SKILLS_EXTENSION="io.modelcontextprotocol/skills";const PM_MCP_SKILLS_DRAFT_REVISION="SEP-2640@a3e147ca2710f68214247aecc729731ee1ae8d03";const PM_MCP_SKILLS_SERVER_CAPABILITY=Object.freeze({revision:PM_MCP_SKILLS_DRAFT_REVISION,status:"draft",directoryRead:true});function assertPmMcpSkillsCapability(context,directoryRead=false){const extensions=context.clientCapabilities.extensions;const declaration=isMcpRecord(extensions)?extensions[PM_MCP_SKILLS_EXTENSION]:void 0;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}}})}}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}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)}#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.")}}#encodeCursor(offset,scope){return Buffer.from(JSON.stringify({fingerprint:this.#fingerprint,offset,scope})).toString("base64url")}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(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(uri){const match=/^skill:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)\/SKILL\.md$/u.exec(uri);const skill=match?this.#skills.get(match[1]):void 0;if(!skill)skillError(`Unknown pm MCP skill: ${uri}.`,{field:"uri"});return projectSkill(skill)}read(uri){const match=/^skill:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)\/(.+)$/u.exec(uri);const skill=match?this.#skills.get(match[1]):void 0;const relative=match?.[2]??"";const bytes=skill&&relative?skill.files.get(relative):void 0;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}]}}readDirectory(uri,options={}){const match=/^skill:\/\/([a-z0-9]+(?:-[a-z0-9]+)*)(?:\/(.+))?$/u.exec(uri);const skill=match?this.#skills.get(match[1]):void 0;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)}:{}}}}export{PM_MCP_SKILLS_DRAFT_REVISION,PM_MCP_SKILLS_EXTENSION,PM_MCP_SKILLS_SERVER_CAPABILITY,PM_MCP_SKILL_LIMITS,PmMcpSkillRegistry,assertPmMcpSkillsCapability};
 //# sourceMappingURL=skills.js.map
-//# debugId=5f60bc89-c81b-57ee-a8f2-0d0b18d0af1b

package/dist/sdk/mcp/subscriptions.js

@@ -1,212 +1,2 @@
-/**
- * @module sdk/mcp/subscriptions
- *
- * Implements transport-neutral MCP 2026-07-28 subscription filtering,
- * acknowledgment, notification correlation, and graceful closure.
- */
-
-!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]="cb791784-bde2-5b1d-b5df-038282816043")}catch(e){}}();
-import { PM_MCP_ERROR_CODES, PmMcpProtocolError, attachMcpServerInfo, isMcpRecord, } from "./protocol.js";
-/** Notification/result metadata key that correlates a subscription stream. */
-export const PM_MCP_SUBSCRIPTION_ID_META_KEY = "io.modelcontextprotocol/subscriptionId";
-const MAX_RESOURCE_SUBSCRIPTIONS = 256;
-const MAX_RESOURCE_URI_BYTES = 2_048;
-const MCP_SUBSCRIPTION_WRITE_TIMEOUT_MS = 5_000;
-function writeSubscriptionNotification(sink, notification) {
-    return new Promise((resolve, reject) => {
-        const timer = setTimeout(() => reject(new Error("MCP subscription sink write timed out")), MCP_SUBSCRIPTION_WRITE_TIMEOUT_MS);
-        timer.unref();
-        Promise.resolve()
-            .then(() => sink(notification))
-            .then(() => {
-            clearTimeout(timer);
-            resolve();
-        }, (error) => {
-            clearTimeout(timer);
-            reject(error instanceof Error ? error : new Error(String(error)));
-        });
-    });
-}
-function validateOptionalBoolean(value, field) {
-    if (value === undefined)
-        return undefined;
-    if (typeof value !== "boolean") {
-        throw new PmMcpProtocolError("Invalid MCP subscription filter", PM_MCP_ERROR_CODES.invalidParams, { field: `notifications.${field}`, expected: "boolean" });
-    }
-    return value || undefined;
-}
-/** Validate and clone one subscription notification filter. */
-export function parseMcpSubscriptionFilter(value) {
-    if (!isMcpRecord(value)) {
-        throw new PmMcpProtocolError("Invalid MCP subscription filter", PM_MCP_ERROR_CODES.invalidParams, { field: "notifications", expected: "object" });
-    }
-    const toolsListChanged = validateOptionalBoolean(value.toolsListChanged, "toolsListChanged");
-    const promptsListChanged = validateOptionalBoolean(value.promptsListChanged, "promptsListChanged");
-    const resourcesListChanged = validateOptionalBoolean(value.resourcesListChanged, "resourcesListChanged");
-    let resourceSubscriptions;
-    if (value.resourceSubscriptions !== undefined) {
-        if (!Array.isArray(value.resourceSubscriptions) ||
-            value.resourceSubscriptions.length > MAX_RESOURCE_SUBSCRIPTIONS) {
-            throw new PmMcpProtocolError("Invalid MCP resource subscriptions", PM_MCP_ERROR_CODES.invalidParams, {
-                field: "notifications.resourceSubscriptions",
-                maximum: MAX_RESOURCE_SUBSCRIPTIONS,
-            });
-        }
-        const unique = new Set();
-        for (const entry of value.resourceSubscriptions) {
-            if (typeof entry !== "string" ||
-                entry.trim().length === 0 ||
-                Buffer.byteLength(entry, "utf8") > MAX_RESOURCE_URI_BYTES) {
-                throw new PmMcpProtocolError("Invalid MCP resource subscription URI", PM_MCP_ERROR_CODES.invalidParams, {
-                    field: "notifications.resourceSubscriptions",
-                    maximumBytes: MAX_RESOURCE_URI_BYTES,
-                });
-            }
-            unique.add(entry);
-        }
-        if (unique.size > 0)
-            resourceSubscriptions = [...unique].sort();
-    }
-    return {
-        ...(toolsListChanged ? { toolsListChanged } : {}),
-        ...(promptsListChanged ? { promptsListChanged } : {}),
-        ...(resourcesListChanged ? { resourcesListChanged } : {}),
-        ...(resourceSubscriptions ? { resourceSubscriptions } : {}),
-    };
-}
-/** Intersect a requested filter with notification capabilities the server advertises. */
-export function resolveMcpAcknowledgedSubscriptionFilter(requested, capabilities) {
-    return {
-        ...(requested.toolsListChanged && capabilities.tools?.listChanged
-            ? { toolsListChanged: true }
-            : {}),
-        ...(requested.promptsListChanged && capabilities.prompts?.listChanged
-            ? { promptsListChanged: true }
-            : {}),
-        ...(requested.resourcesListChanged && capabilities.resources?.listChanged
-            ? { resourcesListChanged: true }
-            : {}),
-        ...(requested.resourceSubscriptions && capabilities.resources?.subscribe
-            ? { resourceSubscriptions: [...requested.resourceSubscriptions] }
-            : {}),
-    };
-}
-/** Manage concurrent stateless subscriptions without retaining client sessions. */
-export class PmMcpSubscriptionRegistry {
-    #capabilities;
-    #records = new Map();
-    #serverInfo;
-    /** Create a registry shared by one concrete transport process. */
-    constructor(input) {
-        this.#capabilities = structuredClone(input.capabilities);
-        this.#serverInfo = { ...input.serverInfo };
-    }
-    /** Number of currently open request-scoped subscription streams. */
-    get size() {
-        return this.#records.size;
-    }
-    /** Open a subscription and emit its required first acknowledgment. */
-    async open(input) {
-        if (this.#records.has(input.id)) {
-            throw new PmMcpProtocolError("MCP subscription id is already active", PM_MCP_ERROR_CODES.invalidParams, { subscriptionId: input.id });
-        }
-        const filter = resolveMcpAcknowledgedSubscriptionFilter(parseMcpSubscriptionFilter(input.notifications), this.#capabilities);
-        const record = {
-            filter,
-            sink: input.sink,
-            writeQueue: Promise.resolve(),
-        };
-        this.#records.set(input.id, record);
-        try {
-            await this.#deliver(input.id, record, {
-                jsonrpc: "2.0",
-                method: "notifications/subscriptions/acknowledged",
-                params: {
-                    _meta: { [PM_MCP_SUBSCRIPTION_ID_META_KEY]: input.id },
-                    notifications: structuredClone(filter),
-                },
-            }, true);
-        }
-        catch (error) {
-            this.#records.delete(input.id);
-            throw error;
-        }
-        return structuredClone(filter);
-    }
-    /** Emit one list-change notification only to streams that opted into it. */
-    async emitListChanged(family) {
-        const field = `${family}ListChanged`;
-        const method = `notifications/${family}/list_changed`;
-        const writes = [];
-        for (const [id, record] of this.#records) {
-            if (record.filter[field] !== true)
-                continue;
-            writes.push(this.#deliver(id, record, {
-                jsonrpc: "2.0",
-                method,
-                params: {
-                    _meta: { [PM_MCP_SUBSCRIPTION_ID_META_KEY]: id },
-                },
-            }));
-        }
-        return (await Promise.all(writes)).filter(Boolean).length;
-    }
-    /** Emit a resource update only to streams that opted into the exact URI. */
-    async emitResourceUpdated(uri) {
-        const writes = [];
-        for (const [id, record] of this.#records) {
-            if (!record.filter.resourceSubscriptions?.includes(uri))
-                continue;
-            writes.push(this.#deliver(id, record, {
-                jsonrpc: "2.0",
-                method: "notifications/resources/updated",
-                params: {
-                    _meta: { [PM_MCP_SUBSCRIPTION_ID_META_KEY]: id },
-                    uri,
-                },
-            }));
-        }
-        return (await Promise.all(writes)).filter(Boolean).length;
-    }
-    async #deliver(id, record, notification, propagateFailure = false) {
-        const pending = record.writeQueue.then(async () => {
-            if (this.#records.get(id) !== record)
-                return false;
-            try {
-                await writeSubscriptionNotification(record.sink, notification);
-                return true;
-            }
-            catch (error) {
-                if (this.#records.get(id) === record)
-                    this.#records.delete(id);
-                if (propagateFailure)
-                    throw error;
-                return false;
-            }
-        });
-        record.writeQueue = pending.then(() => undefined, () => undefined);
-        return pending;
-    }
-    /** Gracefully close one subscription and return its final modern result. */
-    close(id) {
-        if (!this.#records.delete(id))
-            return undefined;
-        return {
-            ...attachMcpServerInfo({
-                resultType: "complete",
-                _meta: { [PM_MCP_SUBSCRIPTION_ID_META_KEY]: id },
-            }, this.#serverInfo),
-        };
-    }
-    /** Gracefully close every stream and preserve stable creation order. */
-    closeAll() {
-        const closed = [];
-        for (const id of this.#records.keys()) {
-            const result = this.close(id);
-            closed.push({ id, result });
-        }
-        return closed;
-    }
-}
+!(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]="f87864d3-e499-57f7-b1e3-4ea3f30b7725")}catch(e2){}})();import{PM_MCP_ERROR_CODES,PmMcpProtocolError,attachMcpServerInfo,isMcpRecord}from"./protocol.js";const PM_MCP_SUBSCRIPTION_ID_META_KEY="io.modelcontextprotocol/subscriptionId";const MAX_RESOURCE_SUBSCRIPTIONS=256;const MAX_RESOURCE_URI_BYTES=2048;const MCP_SUBSCRIPTION_WRITE_TIMEOUT_MS=5e3;function writeSubscriptionNotification(sink,notification){return new Promise((resolve,reject)=>{const timer=setTimeout(()=>reject(new Error("MCP subscription sink write timed out")),MCP_SUBSCRIPTION_WRITE_TIMEOUT_MS);timer.unref();Promise.resolve().then(()=>sink(notification)).then(()=>{clearTimeout(timer);resolve()},error=>{clearTimeout(timer);reject(error instanceof Error?error:new Error(String(error)))})})}function validateOptionalBoolean(value,field){if(value===void 0)return void 0;if(typeof value!=="boolean"){throw new PmMcpProtocolError("Invalid MCP subscription filter",PM_MCP_ERROR_CODES.invalidParams,{field:`notifications.${field}`,expected:"boolean"})}return value||void 0}function parseMcpSubscriptionFilter(value){if(!isMcpRecord(value)){throw new PmMcpProtocolError("Invalid MCP subscription filter",PM_MCP_ERROR_CODES.invalidParams,{field:"notifications",expected:"object"})}const toolsListChanged=validateOptionalBoolean(value.toolsListChanged,"toolsListChanged");const promptsListChanged=validateOptionalBoolean(value.promptsListChanged,"promptsListChanged");const resourcesListChanged=validateOptionalBoolean(value.resourcesListChanged,"resourcesListChanged");let resourceSubscriptions;if(value.resourceSubscriptions!==void 0){if(!Array.isArray(value.resourceSubscriptions)||value.resourceSubscriptions.length>MAX_RESOURCE_SUBSCRIPTIONS){throw new PmMcpProtocolError("Invalid MCP resource subscriptions",PM_MCP_ERROR_CODES.invalidParams,{field:"notifications.resourceSubscriptions",maximum:MAX_RESOURCE_SUBSCRIPTIONS})}const unique=new Set;for(const entry of value.resourceSubscriptions){if(typeof entry!=="string"||entry.trim().length===0||Buffer.byteLength(entry,"utf8")>MAX_RESOURCE_URI_BYTES){throw new PmMcpProtocolError("Invalid MCP resource subscription URI",PM_MCP_ERROR_CODES.invalidParams,{field:"notifications.resourceSubscriptions",maximumBytes:MAX_RESOURCE_URI_BYTES})}unique.add(entry)}if(unique.size>0)resourceSubscriptions=[...unique].sort()}return{...toolsListChanged?{toolsListChanged}:{},...promptsListChanged?{promptsListChanged}:{},...resourcesListChanged?{resourcesListChanged}:{},...resourceSubscriptions?{resourceSubscriptions}:{}}}function resolveMcpAcknowledgedSubscriptionFilter(requested,capabilities){return{...requested.toolsListChanged&&capabilities.tools?.listChanged?{toolsListChanged:true}:{},...requested.promptsListChanged&&capabilities.prompts?.listChanged?{promptsListChanged:true}:{},...requested.resourcesListChanged&&capabilities.resources?.listChanged?{resourcesListChanged:true}:{},...requested.resourceSubscriptions&&capabilities.resources?.subscribe?{resourceSubscriptions:[...requested.resourceSubscriptions]}:{}}}class PmMcpSubscriptionRegistry{#capabilities;#records=new Map;#serverInfo;constructor(input){this.#capabilities=structuredClone(input.capabilities);this.#serverInfo={...input.serverInfo}}get size(){return this.#records.size}async open(input){if(this.#records.has(input.id)){throw new PmMcpProtocolError("MCP subscription id is already active",PM_MCP_ERROR_CODES.invalidParams,{subscriptionId:input.id})}const filter=resolveMcpAcknowledgedSubscriptionFilter(parseMcpSubscriptionFilter(input.notifications),this.#capabilities);const record={filter,sink:input.sink,writeQueue:Promise.resolve()};this.#records.set(input.id,record);try{await this.#deliver(input.id,record,{jsonrpc:"2.0",method:"notifications/subscriptions/acknowledged",params:{_meta:{[PM_MCP_SUBSCRIPTION_ID_META_KEY]:input.id},notifications:structuredClone(filter)}},true)}catch(error){this.#records.delete(input.id);throw error}return structuredClone(filter)}async emitListChanged(family){const field=`${family}ListChanged`;const method=`notifications/${family}/list_changed`;const writes=[];for(const[id,record]of this.#records){if(record.filter[field]!==true)continue;writes.push(this.#deliver(id,record,{jsonrpc:"2.0",method,params:{_meta:{[PM_MCP_SUBSCRIPTION_ID_META_KEY]:id}}}))}return(await Promise.all(writes)).filter(Boolean).length}async emitResourceUpdated(uri){const writes=[];for(const[id,record]of this.#records){if(!record.filter.resourceSubscriptions?.includes(uri))continue;writes.push(this.#deliver(id,record,{jsonrpc:"2.0",method:"notifications/resources/updated",params:{_meta:{[PM_MCP_SUBSCRIPTION_ID_META_KEY]:id},uri}}))}return(await Promise.all(writes)).filter(Boolean).length}async#deliver(id,record,notification,propagateFailure=false){const pending=record.writeQueue.then(async()=>{if(this.#records.get(id)!==record)return false;try{await writeSubscriptionNotification(record.sink,notification);return true}catch(error){if(this.#records.get(id)===record)this.#records.delete(id);if(propagateFailure)throw error;return false}});record.writeQueue=pending.then(()=>void 0,()=>void 0);return pending}close(id){if(!this.#records.delete(id))return void 0;return{...attachMcpServerInfo({resultType:"complete",_meta:{[PM_MCP_SUBSCRIPTION_ID_META_KEY]:id}},this.#serverInfo)}}closeAll(){const closed=[];for(const id of this.#records.keys()){const result=this.close(id);closed.push({id,result})}return closed}}export{PM_MCP_SUBSCRIPTION_ID_META_KEY,PmMcpSubscriptionRegistry,parseMcpSubscriptionFilter,resolveMcpAcknowledgedSubscriptionFilter};
 //# sourceMappingURL=subscriptions.js.map
-//# debugId=cb791784-bde2-5b1d-b5df-038282816043