@graphorin/skills 0.5.0

package/dist/loader/index.js

@@ -0,0 +1,463 @@
+import { InputFilterRequiredError, SkillFrontmatterConflictError, SkillLoadError, SkillRequiredFieldMissingError, SkillRuntimeCompatError } from "../errors/index.js";
+import { parseAllowedToolsValue, parseFrontmatterYaml, parseHandoffInputFilter, parseToolsField, splitSkillMd, validateFrontmatter } from "../frontmatter/index.js";
+import { extname, join, relative, resolve, sep } from "node:path";
+import { readFile, readdir, stat } from "node:fs/promises";
+import { installSkillFromGit, installSkillFromNpm, resolveTrustPolicy, verifySkillSignature } from "@graphorin/security/supply-chain";
+
+//#region src/loader/index.ts
+const SKILL_MANIFEST_FILENAME = "SKILL.md";
+const DEFAULT_MEDIA_TYPES = Object.freeze({
+	".md": "text/markdown; charset=utf-8",
+	".txt": "text/plain; charset=utf-8",
+	".json": "application/json",
+	".yaml": "application/yaml",
+	".yml": "application/yaml",
+	".ts": "text/typescript; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".cjs": "text/javascript; charset=utf-8",
+	".py": "text/x-python; charset=utf-8",
+	".html": "text/html; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".svg": "image/svg+xml",
+	".pdf": "application/pdf"
+});
+/**
+* Load a single skill from any supported source. The loader runs the
+* full frontmatter validator and resolves the supply-chain trust
+* policy so the returned {@link Skill} is ready to be inserted into a
+* `SkillRegistry`.
+*
+* @stable
+*/
+async function loadSkillFromSource(source, options = {}) {
+	switch (source.kind) {
+		case "folder": return loadFromFolder(source.path, source, options);
+		case "inline": return loadFromInline(source, options);
+		case "npm-package": {
+			const installArgs = { packageName: source.packageName };
+			if (source.version !== void 0) installArgs.version = source.version;
+			if (source.trustLevel !== void 0) installArgs.trustLevel = source.trustLevel;
+			if (options.supplyChainPolicy !== void 0) installArgs.policy = options.supplyChainPolicy;
+			if (options.signal !== void 0) installArgs.signal = options.signal;
+			const status = await installSkillFromNpm(installArgs);
+			const installPath = status.installPath;
+			if (installPath === void 0) throw new SkillLoadError(source.packageName, "npm install completed without an install path; cannot continue.");
+			return loadFromFolder(await locateSkillRoot(installPath, source.packageName), source, options, status.signature);
+		}
+		case "git-repo": {
+			const installArgs = { repoUrl: source.url };
+			if (source.ref !== void 0) installArgs.ref = source.ref;
+			if (source.trustLevel !== void 0) installArgs.trustLevel = source.trustLevel;
+			if (options.supplyChainPolicy !== void 0) installArgs.policy = options.supplyChainPolicy;
+			if (options.signal !== void 0) installArgs.signal = options.signal;
+			const status = await installSkillFromGit(installArgs);
+			const installPath = status.installPath;
+			if (installPath === void 0) throw new SkillLoadError(source.url, "git clone completed without a clone path; cannot continue.");
+			return loadFromFolder(await locateSkillRoot(installPath, source.url), source, options, status.signature);
+		}
+		default: throw new SkillLoadError("<unknown>", "unsupported skill source.");
+	}
+}
+/**
+* Load multiple skills concurrently. The sources are loaded in parallel and
+* the returned array preserves input order. When `throwOnSourceError === false`
+* (default) a failing source is logged and skipped; otherwise the first
+* rejection propagates out unchanged.
+*
+* @stable
+*/
+async function loadSkills(sources, options = {}) {
+	const { throwOnSourceError = false, ...inner } = options;
+	const loaded = await Promise.all(sources.map(async (source) => {
+		try {
+			return await loadSkillFromSource(source, inner);
+		} catch (err) {
+			if (throwOnSourceError) throw err;
+			console.warn(`[graphorin/skills] Failed to load source ${describeSource(source)}: ${err.message}`);
+			return null;
+		}
+	}));
+	return Object.freeze(loaded.filter((skill) => skill !== null));
+}
+async function loadFromInline(source, options) {
+	const trustPolicy = resolveTrustPolicy({
+		kind: "folder",
+		path: source.skill.basePath ?? "<inline>"
+	}, "trusted");
+	const { metadata, diagnostics, body } = parseAndValidate(source.skill.skillMd, options);
+	const resources = (source.skill.resources ?? []).map((entry) => {
+		const relativePath = entry.path;
+		const path = source.skill.basePath !== void 0 ? join(source.skill.basePath, entry.path) : entry.path;
+		const mediaType = options.mediaTypeFor?.(entry.path) ?? guessMediaType(entry.path);
+		return Object.freeze({
+			path,
+			relativePath,
+			...mediaType === void 0 ? {} : { mediaType },
+			async read() {
+				return new TextEncoder().encode(entry.content);
+			},
+			async readText() {
+				return entry.content;
+			}
+		});
+	});
+	return buildSkill({
+		metadata,
+		diagnostics,
+		body,
+		source,
+		trustPolicy,
+		...source.skill.tools === void 0 ? {} : { tools: source.skill.tools },
+		bodyLoader: () => Promise.resolve(body),
+		resourceLoader: () => Promise.resolve(resources)
+	});
+}
+async function loadFromFolder(folderPath, source, options, precomputedSignature) {
+	const absolutePath = resolve(folderPath);
+	let stats;
+	try {
+		stats = await stat(absolutePath);
+	} catch (err) {
+		throw new SkillLoadError(describeSource(source), `Could not stat skill directory '${absolutePath}'.`, { cause: err });
+	}
+	if (!stats.isDirectory()) throw new SkillLoadError(describeSource(source), `Skill source must be a directory; '${absolutePath}' is not.`);
+	const manifestPath = join(absolutePath, SKILL_MANIFEST_FILENAME);
+	let skillMd;
+	try {
+		skillMd = await readFile(manifestPath, "utf8");
+	} catch (err) {
+		throw new SkillLoadError(describeSource(source), `SKILL.md is missing at '${manifestPath}'.`, {
+			hint: "Add a SKILL.md file with a YAML frontmatter block.",
+			cause: err
+		});
+	}
+	const parsed = parseAndValidate(skillMd, options);
+	const { diagnostics, body } = parsed;
+	const effectiveTrust = extractTrustLevel(source) ?? (source.kind === "folder" ? capSelfDeclaredTrust(parsed.metadata.graphorinTrustLevel) : parsed.metadata.graphorinTrustLevel);
+	const metadata = effectiveTrust === parsed.metadata.graphorinTrustLevel ? parsed.metadata : Object.freeze({
+		...parsed.metadata,
+		graphorinTrustLevel: effectiveTrust
+	});
+	let signature = precomputedSignature;
+	if (signature === void 0 && metadata.graphorinSignaturePresent) try {
+		signature = await verifySkillSignature({
+			skillMd,
+			...options.signal === void 0 ? {} : { signal: options.signal }
+		});
+	} catch (err) {
+		console.warn(`[graphorin/skills] Signature verification of '${metadata.name}' failed: ${err.message}`);
+	}
+	return buildSkill({
+		metadata,
+		diagnostics,
+		body,
+		source,
+		trustPolicy: resolveTrustPolicy(source.kind === "folder" ? {
+			kind: "folder",
+			path: absolutePath
+		} : source.kind === "npm-package" ? source.version === void 0 ? {
+			kind: "npm-package",
+			packageName: source.packageName
+		} : {
+			kind: "npm-package",
+			packageName: source.packageName,
+			version: source.version
+		} : source.kind === "git-repo" ? source.ref === void 0 ? {
+			kind: "git-repo",
+			url: source.url
+		} : {
+			kind: "git-repo",
+			url: source.url,
+			ref: source.ref
+		} : {
+			kind: "folder",
+			path: absolutePath
+		}, coerceForSupplyChain(metadata.graphorinTrustLevel)),
+		basePath: absolutePath,
+		...signature === void 0 ? {} : { signature },
+		bodyLoader: () => Promise.resolve(body),
+		resourceLoader: async (signal) => listResources(absolutePath, options, signal)
+	});
+}
+async function listResources(rootPath, options, signal) {
+	const out = [];
+	for await (const file of walk(rootPath, signal)) {
+		const relativePath = relative(rootPath, file);
+		if (relativePath === SKILL_MANIFEST_FILENAME) continue;
+		const mediaType = options.mediaTypeFor?.(relativePath) ?? guessMediaType(relativePath);
+		out.push(Object.freeze({
+			path: file,
+			relativePath: relativePath.split(sep).join("/"),
+			...mediaType === void 0 ? {} : { mediaType },
+			async read(innerSignal) {
+				const buffer = await readFile(file, { ...innerSignal === void 0 ? {} : { signal: innerSignal } });
+				return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);
+			},
+			async readText(innerSignal) {
+				return readFile(file, {
+					encoding: "utf8",
+					...innerSignal === void 0 ? {} : { signal: innerSignal }
+				});
+			}
+		}));
+	}
+	return Object.freeze(out);
+}
+async function* walk(root, signal) {
+	const entries = await readdir(root, { withFileTypes: true });
+	for (const entry of entries) {
+		if (signal?.aborted === true) return;
+		const full = join(root, entry.name);
+		if (entry.isDirectory()) {
+			yield* walk(full, signal);
+			continue;
+		}
+		if (entry.isFile()) yield full;
+	}
+}
+async function locateSkillRoot(installPath, sourceLabel) {
+	const direct = join(installPath, SKILL_MANIFEST_FILENAME);
+	try {
+		await stat(direct);
+		return installPath;
+	} catch {}
+	const nodeModulesRoot = join(installPath, "node_modules", sourceLabel);
+	try {
+		await stat(join(nodeModulesRoot, SKILL_MANIFEST_FILENAME));
+		return nodeModulesRoot;
+	} catch {}
+	const entries = await readdir(installPath, { withFileTypes: true });
+	for (const entry of entries) if (entry.isDirectory()) {
+		const child = join(installPath, entry.name, SKILL_MANIFEST_FILENAME);
+		try {
+			await stat(child);
+			return join(installPath, entry.name);
+		} catch {}
+	}
+	throw new SkillLoadError(sourceLabel, `Could not locate SKILL.md inside '${installPath}'. Expected at the top-level or one folder deep.`);
+}
+function parseAndValidate(skillMd, options) {
+	const split = splitSkillMd(skillMd);
+	const frontmatter = parseFrontmatterYaml(split.frontmatter);
+	const validateOptions = {};
+	if (options.conflictPolicy !== void 0) validateOptions.conflictPolicy = options.conflictPolicy;
+	if (options.unknownFieldPolicy !== void 0) validateOptions.unknownFieldPolicy = options.unknownFieldPolicy;
+	if (options.runtimeVersion !== void 0) validateOptions.runtimeVersion = options.runtimeVersion;
+	const validated = validateFrontmatter(frontmatter, validateOptions);
+	for (const diag of validated.diagnostics) if (diag.severity === "error" && diag.kind === "missing-required-field") throw new SkillRequiredFieldMissingError(diag.field, { ...diag.hint === void 0 ? {} : { hint: diag.hint } });
+	const metadata = buildMetadata(validated, frontmatter);
+	const diagnostics = [...validated.diagnostics];
+	appendUntrustedHandoffDiagnostic(metadata, diagnostics, options.conflictPolicy);
+	appendInvalidFieldTypeDiagnostics(frontmatter, validated, diagnostics);
+	enforceErrorPolicy(metadata, validated, diagnostics, options);
+	return Object.freeze({
+		metadata,
+		diagnostics: Object.freeze(diagnostics),
+		body: split.body
+	});
+}
+/**
+* RP-11(d): a frontmatter field that is present but unparseable must not be
+* silently dropped (`?? []`). Surface an `invalid-field-type` diagnostic so
+* callers can audit the rejected value, as the parser contracts mandate.
+*/
+function appendInvalidFieldTypeDiagnostics(raw, validated, diagnostics) {
+	const handoffRaw = validated.resolved.handoffInputFilter.value;
+	if (handoffRaw !== void 0 && parseHandoffInputFilter(handoffRaw) === null) diagnostics.push(Object.freeze({
+		kind: "invalid-field-type",
+		field: "handoff-input-filter",
+		severity: "warn",
+		message: "'handoff-input-filter' has an unsupported shape; the declaration was ignored.",
+		hint: "Use 'lastUser', 'lastN: <n>', 'none', or 'full'."
+	}));
+	const toolsRaw = raw["graphorin-tools"];
+	if (toolsRaw !== void 0 && parseToolsField(toolsRaw) === null) diagnostics.push(Object.freeze({
+		kind: "invalid-field-type",
+		field: "graphorin-tools",
+		severity: "warn",
+		message: "'graphorin-tools' must be a list of tool declarations; the value was ignored.",
+		hint: "Provide a YAML list, e.g. `graphorin-tools:` with `- name: read_file` entries."
+	}));
+}
+/**
+* RP-11(b): under `conflictPolicy: 'error'`, an error-severity diagnostic
+* fails the load through the matching typed exception instead of being
+* silently surfaced. Default (`'warn'`) keeps these as diagnostics.
+*/
+function enforceErrorPolicy(metadata, validated, diagnostics, options) {
+	if (options.conflictPolicy !== "error") return;
+	for (const diag of diagnostics) {
+		if (diag.severity !== "error") continue;
+		if (diag.kind === "invalid-runtime-compat") {
+			const declared = validated.resolved.runtimeCompat.value;
+			throw new SkillRuntimeCompatError(metadata.name, typeof declared === "string" ? declared : String(declared), options.runtimeVersion ?? "<unknown>", diag.hint === void 0 ? void 0 : { hint: diag.hint });
+		}
+		if (diag.kind === "conflict") throw new SkillFrontmatterConflictError(metadata.name, diag.field, [diag.field], diag.hint === void 0 ? void 0 : { hint: diag.hint });
+	}
+}
+function buildMetadata(validated, raw) {
+	const name = String(validated.resolved.name.value ?? "").trim();
+	const description = String(validated.resolved.description.value ?? "").trim();
+	const allowedToolsRaw = validated.resolved.allowedTools.value;
+	const allowedTools = allowedToolsRaw === void 0 ? void 0 : parseAllowedToolsValue(allowedToolsRaw);
+	const handoffFilter = validated.resolved.handoffInputFilter.value === void 0 ? void 0 : parseHandoffInputFilter(validated.resolved.handoffInputFilter.value);
+	const trustLevelRaw = validated.resolved.trustLevel.value;
+	const trustLevel = (() => {
+		if (trustLevelRaw === "trusted" || trustLevelRaw === "trusted-with-scripts" || trustLevelRaw === "untrusted" || trustLevelRaw === "unknown") return trustLevelRaw;
+		return "unknown";
+	})();
+	const sandbox = validated.resolved.sandbox.value;
+	const sensitivity = validated.resolved.sensitivity.value;
+	const sensitivityDefaultsRaw = validated.resolved.sensitivityDefaults.value;
+	const sensitivityDefaults = sensitivityDefaultsRaw !== null && typeof sensitivityDefaultsRaw === "object" ? Object.freeze({ ...sensitivityDefaultsRaw }) : void 0;
+	const metadataObj = validated.resolved.metadata.value;
+	const metadataValue = metadataObj !== null && typeof metadataObj === "object" ? Object.freeze({ ...metadataObj }) : void 0;
+	const result = {
+		name,
+		description,
+		disableModelInvocation: validated.resolved.disableModelInvocation.value === true,
+		graphorinTrustLevel: trustLevel,
+		graphorinSignaturePresent: "graphorin-signature" in raw,
+		raw: Object.freeze({ ...raw })
+	};
+	if (typeof validated.resolved.license.value === "string") result.license = validated.resolved.license.value;
+	if (typeof validated.resolved.compatibility.value === "string") result.compatibility = validated.resolved.compatibility.value;
+	if (metadataValue !== void 0) result.metadata = metadataValue;
+	if (allowedTools !== void 0 && allowedTools !== null) result.allowedTools = Object.freeze([...allowedTools]);
+	if (typeof validated.resolved.runtimeCompat.value === "string") result.graphorinRuntimeCompat = validated.resolved.runtimeCompat.value;
+	if (typeof sensitivity === "string") result.graphorinSensitivity = sensitivity;
+	if (sensitivityDefaults !== void 0) result.graphorinSensitivityDefaults = sensitivityDefaults;
+	if (sandbox !== null && typeof sandbox === "object") result.graphorinSandbox = Object.freeze({ ...sandbox });
+	if (handoffFilter !== void 0 && handoffFilter !== null) result.graphorinHandoffInputFilter = handoffFilter;
+	if (typeof validated.resolved.anthropicSpec.value === "string") result.graphorinAnthropicSpec = validated.resolved.anthropicSpec.value;
+	if (typeof validated.resolved.version.value === "string") result.graphorinVersion = validated.resolved.version.value;
+	return Object.freeze(result);
+}
+function appendUntrustedHandoffDiagnostic(metadata, diagnostics, conflictPolicy = "warn") {
+	if (metadata.graphorinTrustLevel === "untrusted") {
+		if (metadata.graphorinHandoffInputFilter?.kind === "full") diagnostics.push(Object.freeze({
+			kind: "untrusted-handoff-filter-required",
+			field: "graphorin-handoff-input-filter",
+			severity: "warn",
+			message: `Untrusted skill '${metadata.name}' declared 'graphorin-handoff-input-filter: full'. The full-message filter is rejected for untrusted skills; the runtime will fall back to 'lastUser'.`,
+			hint: "Replace 'full' with 'lastUser' (or another bounded filter) to silence this diagnostic."
+		}));
+		else if (metadata.graphorinHandoffInputFilter === void 0) diagnostics.push(Object.freeze({
+			kind: "untrusted-handoff-filter-required",
+			field: "graphorin-handoff-input-filter",
+			severity: conflictPolicy === "error" ? "error" : "warn",
+			message: `Untrusted skill '${metadata.name}' did not declare 'graphorin-handoff-input-filter'. The runtime will throw if the skill invokes Agent.toTool()/handoff().`,
+			hint: "Add 'graphorin-handoff-input-filter: lastUser' to the SKILL.md frontmatter."
+		}));
+	}
+}
+function buildSkill(args) {
+	let bodyCache = null;
+	let resourcesCache = null;
+	let bodyPromise = null;
+	let resourcesPromise = null;
+	const toolDeclarations = parseToolsField(args.metadata.raw["graphorin-tools"]) ?? [];
+	const tools = Object.freeze([...args.tools ?? []]);
+	return Object.freeze({
+		metadata: args.metadata,
+		source: args.source,
+		...args.basePath === void 0 ? {} : { basePath: args.basePath },
+		trustPolicy: args.trustPolicy,
+		...args.signature === void 0 ? {} : { signature: args.signature },
+		async body(_signal) {
+			if (bodyCache !== null) return bodyCache;
+			if (bodyPromise === null) bodyPromise = args.bodyLoader().then((value) => {
+				bodyCache = value;
+				return value;
+			});
+			return bodyPromise;
+		},
+		async resources(signal) {
+			if (resourcesCache !== null) return resourcesCache;
+			if (resourcesPromise === null) resourcesPromise = args.resourceLoader(signal).then((value) => {
+				resourcesCache = value;
+				return value;
+			});
+			return resourcesPromise;
+		},
+		tools() {
+			return tools;
+		},
+		toolDeclarations() {
+			return toolDeclarations;
+		},
+		diagnostics() {
+			return args.diagnostics;
+		}
+	});
+}
+function describeSource(source) {
+	switch (source.kind) {
+		case "folder": return `folder:${source.path}`;
+		case "npm-package": return source.version === void 0 ? `npm:${source.packageName}` : `npm:${source.packageName}@${source.version}`;
+		case "git-repo": return source.ref === void 0 ? `git:${source.url}` : `git:${source.url}@${source.ref}`;
+		case "inline": return "inline";
+		default: return "unknown";
+	}
+}
+function extractTrustLevel(source) {
+	if (source.kind === "npm-package" || source.kind === "git-repo" || source.kind === "folder") return source.trustLevel;
+}
+/**
+* Cap a folder skill's self-declared trust level. A directory on disk —
+* possibly downloaded from the internet — cannot self-promote to a trusted
+* tier without an operator override (RP-9): `trusted` /
+* `trusted-with-scripts` collapse to `'unknown'` (sandbox forced, signature
+* optional, outputs taint-marked), while `untrusted` / `unknown` pass
+* through unchanged.
+*/
+function capSelfDeclaredTrust(level) {
+	return level === "trusted" || level === "trusted-with-scripts" ? "unknown" : level;
+}
+/**
+* Translate the loader's four-valued trust level into the three-
+* valued trust level the supply-chain installer expects.
+*
+* The 'unknown' value collapses to 'untrusted' so the supply-chain
+* resolver picks the strict signature + `--ignore-scripts` policy.
+* The loader keeps the original 'unknown' on the skill's metadata
+* record so the runtime sandbox tier resolver continues to apply
+* the correct policy.
+*/
+function coerceForSupplyChain(level) {
+	if (level === "unknown") return "untrusted";
+	return level;
+}
+function guessMediaType(path) {
+	return DEFAULT_MEDIA_TYPES[extname(path).toLowerCase()];
+}
+/**
+* Required handoff-filter declaration helper. Returns the typed
+* declaration the loader parsed from frontmatter; throws
+* {@link InputFilterRequiredError} when the skill is untrusted and the
+* field is missing. Used by the agent runtime in Phase 12 right
+* before instantiating an untrusted skill's sub-agent.
+*
+* @stable
+*/
+function requireHandoffInputFilter(metadata) {
+	if (metadata.graphorinHandoffInputFilter !== void 0) {
+		if (metadata.graphorinTrustLevel === "untrusted" && metadata.graphorinHandoffInputFilter.kind === "full") return Object.freeze({ kind: "lastUser" });
+		return metadata.graphorinHandoffInputFilter;
+	}
+	if (metadata.graphorinTrustLevel === "untrusted") throw new InputFilterRequiredError(metadata.name);
+	if (metadata.graphorinTrustLevel === "unknown") throw new InputFilterRequiredError(metadata.name);
+	return Object.freeze({
+		kind: "lastN",
+		n: 10
+	});
+}
+
+//#endregion
+export { loadSkillFromSource, loadSkills, requireHandoffInputFilter };
+//# sourceMappingURL=index.js.map

package/dist/loader/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["DEFAULT_MEDIA_TYPES: Readonly<Record<string, string>>","installArgs: Parameters<typeof installSkillFromNpm>[0]","installArgs: Parameters<typeof installSkillFromGit>[0]","resources: SkillResource[]","stats: Stats","skillMd: string","effectiveTrust: SkillsTrustLevel","metadata: SkillMetadata","signature: SkillSignatureVerificationResult | undefined","out: SkillResource[]","validateOptions: Parameters<typeof validateFrontmatter>[1]","diagnostics: FrontmatterDiagnostic[]","trustLevel: SkillsTrustLevel","result: Mutable<SkillMetadata>","bodyCache: string | null","resourcesCache: ReadonlyArray<SkillResource> | null","bodyPromise: Promise<string> | null","resourcesPromise: Promise<ReadonlyArray<SkillResource>> | null"],"sources":["../../src/loader/index.ts"],"sourcesContent":["/**\n * Skill loader.\n *\n * Implements three-tier progressive disclosure:\n *\n * - **Tier 1** (always): {@link Skill.metadata} — parsed at load\n *   time from the SKILL.md frontmatter.\n * - **Tier 2** (on activation): {@link Skill.body} — the loader\n *   reads the markdown body lazily; subsequent calls return the\n *   cached value.\n * - **Tier 3** (on demand): {@link Skill.resources} — the loader\n *   walks the skill directory lazily; resource bytes are only read\n *   when {@link SkillResource.read} is invoked.\n *\n * The loader supports four sources:\n *\n * - `{ kind: 'folder', path }`        — read SKILL.md from disk.\n * - `{ kind: 'npm-package', ... }`    — install via the supply-chain\n *   helper from `@graphorin/security/supply-chain`, then read.\n * - `{ kind: 'git-repo', ... }`       — shallow-clone via the\n *   supply-chain helper, then read.\n * - `{ kind: 'inline', skill: ... }`  — caller supplies the parsed\n *   payload; the loader only validates the frontmatter. Useful for\n *   tests and bundled defaults.\n *\n * @packageDocumentation\n */\n\nimport type { Stats } from 'node:fs';\nimport { readdir, readFile, stat } from 'node:fs/promises';\nimport { extname, join, relative, resolve, sep } from 'node:path';\n\nimport {\n  installSkillFromGit,\n  installSkillFromNpm,\n  type ResolvedSkillTrustPolicy,\n  resolveTrustPolicy,\n  type SkillSignatureVerificationResult,\n  type SupplyChainPolicy,\n  verifySkillSignature,\n} from '@graphorin/security/supply-chain';\n\nimport {\n  InputFilterRequiredError,\n  SkillFrontmatterConflictError,\n  SkillLoadError,\n  SkillRequiredFieldMissingError,\n  SkillRuntimeCompatError,\n} from '../errors/index.js';\nimport {\n  parseAllowedToolsValue,\n  parseFrontmatterYaml,\n  parseHandoffInputFilter,\n  parseToolsField,\n  splitSkillMd,\n  type ValidatedFrontmatter,\n  validateFrontmatter,\n} from '../frontmatter/index.js';\nimport type {\n  FrontmatterDiagnostic,\n  FrontmatterValidatorPolicy,\n  HandoffInputFilterDeclaration,\n  InlineSkillTool,\n  Skill,\n  SkillMetadata,\n  SkillResource,\n  SkillSource,\n  SkillsTrustLevel,\n  SkillToolDeclaration,\n  UnknownFieldPolicy,\n} from '../types/index.js';\n\n/** Options forwarded to {@link loadSkillFromSource}. */\nexport interface LoadSkillOptions {\n  readonly conflictPolicy?: FrontmatterValidatorPolicy;\n  readonly unknownFieldPolicy?: UnknownFieldPolicy;\n  readonly runtimeVersion?: string;\n  readonly supplyChainPolicy?: SupplyChainPolicy;\n  readonly signal?: AbortSignal;\n  /** Override the bundled MIME-type guesser for resource files. */\n  readonly mediaTypeFor?: (path: string) => string | undefined;\n}\n\n/** Aggregate options accepted by {@link loadSkills}. */\nexport interface LoadSkillsOptions extends LoadSkillOptions {\n  /**\n   * Fail fast if any source produces a {@link SkillLoadError}. When\n   * `false` (default) the loader logs the source path on the\n   * diagnostic and continues with the next source.\n   */\n  readonly throwOnSourceError?: boolean;\n}\n\nconst SKILL_MANIFEST_FILENAME = 'SKILL.md';\n\nconst DEFAULT_MEDIA_TYPES: Readonly<Record<string, string>> = Object.freeze({\n  '.md': 'text/markdown; charset=utf-8',\n  '.txt': 'text/plain; charset=utf-8',\n  '.json': 'application/json',\n  '.yaml': 'application/yaml',\n  '.yml': 'application/yaml',\n  '.ts': 'text/typescript; charset=utf-8',\n  '.js': 'text/javascript; charset=utf-8',\n  '.mjs': 'text/javascript; charset=utf-8',\n  '.cjs': 'text/javascript; charset=utf-8',\n  '.py': 'text/x-python; charset=utf-8',\n  '.html': 'text/html; charset=utf-8',\n  '.css': 'text/css; charset=utf-8',\n  '.png': 'image/png',\n  '.jpg': 'image/jpeg',\n  '.jpeg': 'image/jpeg',\n  '.gif': 'image/gif',\n  '.svg': 'image/svg+xml',\n  '.pdf': 'application/pdf',\n});\n\n/**\n * Load a single skill from any supported source. The loader runs the\n * full frontmatter validator and resolves the supply-chain trust\n * policy so the returned {@link Skill} is ready to be inserted into a\n * `SkillRegistry`.\n *\n * @stable\n */\nexport async function loadSkillFromSource(\n  source: SkillSource,\n  options: LoadSkillOptions = {},\n): Promise<Skill> {\n  switch (source.kind) {\n    case 'folder':\n      return loadFromFolder(source.path, source, options);\n    case 'inline':\n      return loadFromInline(source, options);\n    case 'npm-package': {\n      const installArgs: Parameters<typeof installSkillFromNpm>[0] = {\n        packageName: source.packageName,\n      };\n      if (source.version !== undefined)\n        (installArgs as Mutable<typeof installArgs>).version = source.version;\n      if (source.trustLevel !== undefined)\n        (installArgs as Mutable<typeof installArgs>).trustLevel = source.trustLevel;\n      if (options.supplyChainPolicy !== undefined)\n        (installArgs as Mutable<typeof installArgs>).policy = options.supplyChainPolicy;\n      if (options.signal !== undefined)\n        (installArgs as Mutable<typeof installArgs>).signal = options.signal;\n      const status = await installSkillFromNpm(installArgs);\n      const installPath = status.installPath;\n      if (installPath === undefined) {\n        throw new SkillLoadError(\n          source.packageName,\n          'npm install completed without an install path; cannot continue.',\n        );\n      }\n      const resolved = await locateSkillRoot(installPath, source.packageName);\n      return loadFromFolder(resolved, source, options, status.signature);\n    }\n    case 'git-repo': {\n      const installArgs: Parameters<typeof installSkillFromGit>[0] = {\n        repoUrl: source.url,\n      };\n      if (source.ref !== undefined) (installArgs as Mutable<typeof installArgs>).ref = source.ref;\n      if (source.trustLevel !== undefined)\n        (installArgs as Mutable<typeof installArgs>).trustLevel = source.trustLevel;\n      if (options.supplyChainPolicy !== undefined)\n        (installArgs as Mutable<typeof installArgs>).policy = options.supplyChainPolicy;\n      if (options.signal !== undefined)\n        (installArgs as Mutable<typeof installArgs>).signal = options.signal;\n      const status = await installSkillFromGit(installArgs);\n      const installPath = status.installPath;\n      if (installPath === undefined) {\n        throw new SkillLoadError(\n          source.url,\n          'git clone completed without a clone path; cannot continue.',\n        );\n      }\n      const resolved = await locateSkillRoot(installPath, source.url);\n      return loadFromFolder(resolved, source, options, status.signature);\n    }\n    default: {\n      const exhaustive: never = source;\n      void exhaustive;\n      throw new SkillLoadError('<unknown>', 'unsupported skill source.');\n    }\n  }\n}\n\n/**\n * Load multiple skills concurrently. The sources are loaded in parallel and\n * the returned array preserves input order. When `throwOnSourceError === false`\n * (default) a failing source is logged and skipped; otherwise the first\n * rejection propagates out unchanged.\n *\n * @stable\n */\nexport async function loadSkills(\n  sources: ReadonlyArray<SkillSource>,\n  options: LoadSkillsOptions = {},\n): Promise<ReadonlyArray<Skill>> {\n  const { throwOnSourceError = false, ...inner } = options;\n  const loaded = await Promise.all(\n    sources.map(async (source): Promise<Skill | null> => {\n      try {\n        return await loadSkillFromSource(source, inner);\n      } catch (err) {\n        if (throwOnSourceError) throw err;\n        // We cannot create a Skill from a failed source, but we want to\n        // preserve a structured diagnostic so callers can audit which\n        // sources failed without re-running the loader.\n        // eslint-disable-next-line no-console\n        console.warn(\n          `[graphorin/skills] Failed to load source ${describeSource(source)}: ${(err as Error).message}`,\n        );\n        return null;\n      }\n    }),\n  );\n  return Object.freeze(loaded.filter((skill): skill is Skill => skill !== null));\n}\n\nasync function loadFromInline(\n  source: Extract<SkillSource, { kind: 'inline' }>,\n  options: LoadSkillOptions,\n): Promise<Skill> {\n  const trustPolicy = resolveTrustPolicy(\n    { kind: 'folder', path: source.skill.basePath ?? '<inline>' },\n    'trusted',\n  );\n  const { metadata, diagnostics, body } = parseAndValidate(source.skill.skillMd, options);\n  const resourceList = source.skill.resources ?? [];\n  const resources: SkillResource[] = resourceList.map((entry) => {\n    const relativePath = entry.path;\n    const path =\n      source.skill.basePath !== undefined ? join(source.skill.basePath, entry.path) : entry.path;\n    const mediaType = options.mediaTypeFor?.(entry.path) ?? guessMediaType(entry.path);\n    return Object.freeze({\n      path,\n      relativePath,\n      ...(mediaType === undefined ? {} : { mediaType }),\n      async read() {\n        return new TextEncoder().encode(entry.content);\n      },\n      async readText() {\n        return entry.content;\n      },\n    } satisfies SkillResource);\n  });\n  return buildSkill({\n    metadata,\n    diagnostics,\n    body,\n    source,\n    trustPolicy,\n    ...(source.skill.tools === undefined ? {} : { tools: source.skill.tools }),\n    bodyLoader: () => Promise.resolve(body),\n    resourceLoader: () => Promise.resolve(resources),\n  });\n}\n\nasync function loadFromFolder(\n  folderPath: string,\n  source: SkillSource,\n  options: LoadSkillOptions,\n  precomputedSignature?: SkillSignatureVerificationResult | undefined,\n): Promise<Skill> {\n  const absolutePath = resolve(folderPath);\n  let stats: Stats;\n  try {\n    stats = await stat(absolutePath);\n  } catch (err) {\n    throw new SkillLoadError(\n      describeSource(source),\n      `Could not stat skill directory '${absolutePath}'.`,\n      { cause: err },\n    );\n  }\n  if (!stats.isDirectory()) {\n    throw new SkillLoadError(\n      describeSource(source),\n      `Skill source must be a directory; '${absolutePath}' is not.`,\n    );\n  }\n  const manifestPath = join(absolutePath, SKILL_MANIFEST_FILENAME);\n  let skillMd: string;\n  try {\n    skillMd = await readFile(manifestPath, 'utf8');\n  } catch (err) {\n    throw new SkillLoadError(describeSource(source), `SKILL.md is missing at '${manifestPath}'.`, {\n      hint: 'Add a SKILL.md file with a YAML frontmatter block.',\n      cause: err,\n    });\n  }\n  const parsed = parseAndValidate(skillMd, options);\n  const { diagnostics, body } = parsed;\n  // RP-9: trust is granted by the integrator, never the artifact. An operator\n  // override on the source wins; absent one, a folder's self-declared\n  // 'trusted'/'trusted-with-scripts' is capped at 'unknown' so a downloaded\n  // directory cannot promote itself out of the sandbox + taint-marking. The\n  // resolved level is written back onto the metadata so every downstream\n  // consumer (tool stamping, sandbox tier, inbound sanitization) sees it.\n  const operatorTrust = extractTrustLevel(source);\n  const effectiveTrust: SkillsTrustLevel =\n    operatorTrust ??\n    (source.kind === 'folder'\n      ? capSelfDeclaredTrust(parsed.metadata.graphorinTrustLevel)\n      : parsed.metadata.graphorinTrustLevel);\n  const metadata: SkillMetadata =\n    effectiveTrust === parsed.metadata.graphorinTrustLevel\n      ? parsed.metadata\n      : (Object.freeze({\n          ...parsed.metadata,\n          graphorinTrustLevel: effectiveTrust,\n        }) as SkillMetadata);\n\n  let signature: SkillSignatureVerificationResult | undefined = precomputedSignature;\n  if (signature === undefined && metadata.graphorinSignaturePresent) {\n    try {\n      signature = await verifySkillSignature({\n        skillMd,\n        ...(options.signal === undefined ? {} : { signal: options.signal }),\n      });\n    } catch (err) {\n      // Surface the signature failure as a diagnostic — the supply-\n      // chain installer is the one that decides whether to refuse the\n      // install based on the resolved trust policy. The folder loader\n      // tolerates an unverifiable signature so operators can iterate\n      // on local skills before signing.\n      // eslint-disable-next-line no-console\n      console.warn(\n        `[graphorin/skills] Signature verification of '${metadata.name}' failed: ${(err as Error).message}`,\n      );\n    }\n  }\n\n  const trustPolicy = resolveTrustPolicy(\n    source.kind === 'folder'\n      ? { kind: 'folder', path: absolutePath }\n      : source.kind === 'npm-package'\n        ? source.version === undefined\n          ? { kind: 'npm-package', packageName: source.packageName }\n          : { kind: 'npm-package', packageName: source.packageName, version: source.version }\n        : source.kind === 'git-repo'\n          ? source.ref === undefined\n            ? { kind: 'git-repo', url: source.url }\n            : { kind: 'git-repo', url: source.url, ref: source.ref }\n          : { kind: 'folder', path: absolutePath },\n    coerceForSupplyChain(metadata.graphorinTrustLevel),\n  );\n\n  return buildSkill({\n    metadata,\n    diagnostics,\n    body,\n    source,\n    trustPolicy,\n    basePath: absolutePath,\n    ...(signature === undefined ? {} : { signature }),\n    bodyLoader: () => Promise.resolve(body),\n    resourceLoader: async (signal) => listResources(absolutePath, options, signal),\n  });\n}\n\nasync function listResources(\n  rootPath: string,\n  options: LoadSkillOptions,\n  signal?: AbortSignal,\n): Promise<ReadonlyArray<SkillResource>> {\n  const out: SkillResource[] = [];\n  for await (const file of walk(rootPath, signal)) {\n    const relativePath = relative(rootPath, file);\n    if (relativePath === SKILL_MANIFEST_FILENAME) continue;\n    const mediaType = options.mediaTypeFor?.(relativePath) ?? guessMediaType(relativePath);\n    out.push(\n      Object.freeze({\n        path: file,\n        relativePath: relativePath.split(sep).join('/'),\n        ...(mediaType === undefined ? {} : { mediaType }),\n        async read(innerSignal?: AbortSignal): Promise<Uint8Array> {\n          const buffer = await readFile(file, {\n            ...(innerSignal === undefined ? {} : { signal: innerSignal }),\n          });\n          return new Uint8Array(buffer.buffer, buffer.byteOffset, buffer.byteLength);\n        },\n        async readText(innerSignal?: AbortSignal): Promise<string> {\n          return readFile(file, {\n            encoding: 'utf8',\n            ...(innerSignal === undefined ? {} : { signal: innerSignal }),\n          });\n        },\n      } satisfies SkillResource),\n    );\n  }\n  return Object.freeze(out);\n}\n\nasync function* walk(root: string, signal?: AbortSignal): AsyncIterable<string> {\n  const entries = await readdir(root, { withFileTypes: true });\n  for (const entry of entries) {\n    if (signal?.aborted === true) return;\n    const full = join(root, entry.name);\n    if (entry.isDirectory()) {\n      yield* walk(full, signal);\n      continue;\n    }\n    if (entry.isFile()) {\n      yield full;\n    }\n  }\n}\n\nasync function locateSkillRoot(installPath: string, sourceLabel: string): Promise<string> {\n  const direct = join(installPath, SKILL_MANIFEST_FILENAME);\n  try {\n    await stat(direct);\n    return installPath;\n  } catch {\n    // continue\n  }\n  // RP-10: npm packages land under `node_modules/<packageName>`. The label is\n  // the package name for npm sources; for git it is a URL and this probe\n  // simply misses, falling through to the one-level-deep scan below.\n  const nodeModulesRoot = join(installPath, 'node_modules', sourceLabel);\n  try {\n    await stat(join(nodeModulesRoot, SKILL_MANIFEST_FILENAME));\n    return nodeModulesRoot;\n  } catch {\n    // continue\n  }\n  const entries = await readdir(installPath, { withFileTypes: true });\n  for (const entry of entries) {\n    if (entry.isDirectory()) {\n      const child = join(installPath, entry.name, SKILL_MANIFEST_FILENAME);\n      try {\n        await stat(child);\n        return join(installPath, entry.name);\n      } catch {\n        // continue\n      }\n    }\n  }\n  throw new SkillLoadError(\n    sourceLabel,\n    `Could not locate SKILL.md inside '${installPath}'. Expected at the top-level or one folder deep.`,\n  );\n}\n\ninterface ParsedAndValidated {\n  readonly metadata: SkillMetadata;\n  readonly diagnostics: ReadonlyArray<FrontmatterDiagnostic>;\n  readonly body: string;\n}\n\nfunction parseAndValidate(skillMd: string, options: LoadSkillOptions): ParsedAndValidated {\n  const split = splitSkillMd(skillMd);\n  const frontmatter = parseFrontmatterYaml(split.frontmatter);\n  const validateOptions: Parameters<typeof validateFrontmatter>[1] = {};\n  if (options.conflictPolicy !== undefined)\n    (validateOptions as Mutable<typeof validateOptions>).conflictPolicy = options.conflictPolicy;\n  if (options.unknownFieldPolicy !== undefined)\n    (validateOptions as Mutable<typeof validateOptions>).unknownFieldPolicy =\n      options.unknownFieldPolicy;\n  if (options.runtimeVersion !== undefined)\n    (validateOptions as Mutable<typeof validateOptions>).runtimeVersion = options.runtimeVersion;\n  const validated = validateFrontmatter(frontmatter, validateOptions);\n  for (const diag of validated.diagnostics) {\n    if (diag.severity === 'error' && diag.kind === 'missing-required-field') {\n      throw new SkillRequiredFieldMissingError(diag.field, {\n        ...(diag.hint === undefined ? {} : { hint: diag.hint }),\n      });\n    }\n  }\n  const metadata = buildMetadata(validated, frontmatter);\n  const diagnostics: FrontmatterDiagnostic[] = [...validated.diagnostics];\n  appendUntrustedHandoffDiagnostic(metadata, diagnostics, options.conflictPolicy);\n  appendInvalidFieldTypeDiagnostics(frontmatter, validated, diagnostics);\n  enforceErrorPolicy(metadata, validated, diagnostics, options);\n  return Object.freeze({\n    metadata,\n    diagnostics: Object.freeze(diagnostics),\n    body: split.body,\n  });\n}\n\n/**\n * RP-11(d): a frontmatter field that is present but unparseable must not be\n * silently dropped (`?? []`). Surface an `invalid-field-type` diagnostic so\n * callers can audit the rejected value, as the parser contracts mandate.\n */\nfunction appendInvalidFieldTypeDiagnostics(\n  raw: Record<string, unknown>,\n  validated: ValidatedFrontmatter,\n  diagnostics: FrontmatterDiagnostic[],\n): void {\n  const handoffRaw = validated.resolved.handoffInputFilter.value;\n  if (handoffRaw !== undefined && parseHandoffInputFilter(handoffRaw) === null) {\n    diagnostics.push(\n      Object.freeze({\n        kind: 'invalid-field-type',\n        field: 'handoff-input-filter',\n        severity: 'warn',\n        message: \"'handoff-input-filter' has an unsupported shape; the declaration was ignored.\",\n        hint: \"Use 'lastUser', 'lastN: <n>', 'none', or 'full'.\",\n      }),\n    );\n  }\n  const toolsRaw = raw['graphorin-tools'];\n  if (toolsRaw !== undefined && parseToolsField(toolsRaw) === null) {\n    diagnostics.push(\n      Object.freeze({\n        kind: 'invalid-field-type',\n        field: 'graphorin-tools',\n        severity: 'warn',\n        message: \"'graphorin-tools' must be a list of tool declarations; the value was ignored.\",\n        hint: 'Provide a YAML list, e.g. `graphorin-tools:` with `- name: read_file` entries.',\n      }),\n    );\n  }\n}\n\n/**\n * RP-11(b): under `conflictPolicy: 'error'`, an error-severity diagnostic\n * fails the load through the matching typed exception instead of being\n * silently surfaced. Default (`'warn'`) keeps these as diagnostics.\n */\nfunction enforceErrorPolicy(\n  metadata: SkillMetadata,\n  validated: ValidatedFrontmatter,\n  diagnostics: ReadonlyArray<FrontmatterDiagnostic>,\n  options: LoadSkillOptions,\n): void {\n  if (options.conflictPolicy !== 'error') return;\n  for (const diag of diagnostics) {\n    if (diag.severity !== 'error') continue;\n    if (diag.kind === 'invalid-runtime-compat') {\n      const declared = validated.resolved.runtimeCompat.value;\n      throw new SkillRuntimeCompatError(\n        metadata.name,\n        typeof declared === 'string' ? declared : String(declared),\n        options.runtimeVersion ?? '<unknown>',\n        diag.hint === undefined ? undefined : { hint: diag.hint },\n      );\n    }\n    if (diag.kind === 'conflict') {\n      throw new SkillFrontmatterConflictError(\n        metadata.name,\n        diag.field,\n        [diag.field],\n        diag.hint === undefined ? undefined : { hint: diag.hint },\n      );\n    }\n  }\n}\n\nfunction buildMetadata(\n  validated: ValidatedFrontmatter,\n  raw: Record<string, unknown>,\n): SkillMetadata {\n  const name = String(validated.resolved.name.value ?? '').trim();\n  const description = String(validated.resolved.description.value ?? '').trim();\n  const allowedToolsRaw = validated.resolved.allowedTools.value;\n  const allowedTools =\n    allowedToolsRaw === undefined ? undefined : parseAllowedToolsValue(allowedToolsRaw);\n  const handoffFilter =\n    validated.resolved.handoffInputFilter.value === undefined\n      ? undefined\n      : parseHandoffInputFilter(validated.resolved.handoffInputFilter.value);\n  const trustLevelRaw = validated.resolved.trustLevel.value;\n  // Phase 08 § \"Frontmatter validator\" recognises four explicit trust\n  // levels: 'trusted' | 'trusted-with-scripts' | 'unknown' |\n  // 'untrusted'. A skill that did not declare the field is treated as\n  // 'unknown' (sandbox forced; signature optional) — that is the\n  // default-deny posture per DEC-148 risk mitigation.\n  const trustLevel: SkillsTrustLevel = (() => {\n    if (\n      trustLevelRaw === 'trusted' ||\n      trustLevelRaw === 'trusted-with-scripts' ||\n      trustLevelRaw === 'untrusted' ||\n      trustLevelRaw === 'unknown'\n    ) {\n      return trustLevelRaw;\n    }\n    return 'unknown';\n  })();\n  const sandbox = validated.resolved.sandbox.value;\n  const sensitivity = validated.resolved.sensitivity.value;\n  const sensitivityDefaultsRaw = validated.resolved.sensitivityDefaults.value;\n  const sensitivityDefaults =\n    sensitivityDefaultsRaw !== null && typeof sensitivityDefaultsRaw === 'object'\n      ? Object.freeze({ ...(sensitivityDefaultsRaw as Record<string, string>) })\n      : undefined;\n  const metadataObj = validated.resolved.metadata.value;\n  const metadataValue =\n    metadataObj !== null && typeof metadataObj === 'object'\n      ? Object.freeze({ ...(metadataObj as Record<string, unknown>) })\n      : undefined;\n  const result: Mutable<SkillMetadata> = {\n    name,\n    description,\n    disableModelInvocation: validated.resolved.disableModelInvocation.value === true,\n    graphorinTrustLevel: trustLevel,\n    graphorinSignaturePresent: 'graphorin-signature' in raw,\n    raw: Object.freeze({ ...raw }),\n  };\n  if (typeof validated.resolved.license.value === 'string')\n    result.license = validated.resolved.license.value;\n  if (typeof validated.resolved.compatibility.value === 'string')\n    result.compatibility = validated.resolved.compatibility.value;\n  if (metadataValue !== undefined) result.metadata = metadataValue;\n  if (allowedTools !== undefined && allowedTools !== null)\n    result.allowedTools = Object.freeze([...allowedTools]);\n  if (typeof validated.resolved.runtimeCompat.value === 'string')\n    result.graphorinRuntimeCompat = validated.resolved.runtimeCompat.value;\n  if (typeof sensitivity === 'string') result.graphorinSensitivity = sensitivity;\n  if (sensitivityDefaults !== undefined) result.graphorinSensitivityDefaults = sensitivityDefaults;\n  if (sandbox !== null && typeof sandbox === 'object')\n    result.graphorinSandbox = Object.freeze({ ...(sandbox as Record<string, unknown>) });\n  if (handoffFilter !== undefined && handoffFilter !== null)\n    result.graphorinHandoffInputFilter = handoffFilter;\n  if (typeof validated.resolved.anthropicSpec.value === 'string')\n    result.graphorinAnthropicSpec = validated.resolved.anthropicSpec.value;\n  if (typeof validated.resolved.version.value === 'string')\n    result.graphorinVersion = validated.resolved.version.value;\n  return Object.freeze(result) as SkillMetadata;\n}\n\nfunction appendUntrustedHandoffDiagnostic(\n  metadata: SkillMetadata,\n  diagnostics: FrontmatterDiagnostic[],\n  conflictPolicy: FrontmatterValidatorPolicy = 'warn',\n): void {\n  // Untrusted skills that declared `filter: full` are an explicit\n  // attempt to exfiltrate the entire conversation through a sub-agent\n  // — Phase 08 / ADR-040 mandate that we WARN and ignore. The agent\n  // runtime in Phase 12 will refuse the filter regardless of this\n  // diagnostic.\n  if (metadata.graphorinTrustLevel === 'untrusted') {\n    if (metadata.graphorinHandoffInputFilter?.kind === 'full') {\n      diagnostics.push(\n        Object.freeze({\n          kind: 'untrusted-handoff-filter-required',\n          field: 'graphorin-handoff-input-filter',\n          severity: 'warn',\n          message: `Untrusted skill '${metadata.name}' declared 'graphorin-handoff-input-filter: full'. The full-message filter is rejected for untrusted skills; the runtime will fall back to 'lastUser'.`,\n          hint: \"Replace 'full' with 'lastUser' (or another bounded filter) to silence this diagnostic.\",\n        }),\n      );\n    } else if (metadata.graphorinHandoffInputFilter === undefined) {\n      diagnostics.push(\n        Object.freeze({\n          kind: 'untrusted-handoff-filter-required',\n          field: 'graphorin-handoff-input-filter',\n          severity: conflictPolicy === 'error' ? 'error' : 'warn',\n          message: `Untrusted skill '${metadata.name}' did not declare 'graphorin-handoff-input-filter'. The runtime will throw if the skill invokes Agent.toTool()/handoff().`,\n          hint: \"Add 'graphorin-handoff-input-filter: lastUser' to the SKILL.md frontmatter.\",\n        }),\n      );\n    }\n  }\n}\n\ninterface BuildSkillArgs {\n  readonly metadata: SkillMetadata;\n  readonly diagnostics: ReadonlyArray<FrontmatterDiagnostic>;\n  readonly body: string;\n  readonly source: SkillSource;\n  readonly trustPolicy: ResolvedSkillTrustPolicy;\n  readonly basePath?: string;\n  readonly signature?: SkillSignatureVerificationResult;\n  readonly tools?: ReadonlyArray<InlineSkillTool>;\n  readonly bodyLoader: () => Promise<string>;\n  readonly resourceLoader: (signal?: AbortSignal) => Promise<ReadonlyArray<SkillResource>>;\n}\n\nfunction buildSkill(args: BuildSkillArgs): Skill {\n  let bodyCache: string | null = null;\n  let resourcesCache: ReadonlyArray<SkillResource> | null = null;\n  let bodyPromise: Promise<string> | null = null;\n  let resourcesPromise: Promise<ReadonlyArray<SkillResource>> | null = null;\n  const toolDeclarations = parseToolsField(args.metadata.raw['graphorin-tools']) ?? [];\n  const tools = Object.freeze([...(args.tools ?? [])]);\n  return Object.freeze({\n    metadata: args.metadata,\n    source: args.source,\n    ...(args.basePath === undefined ? {} : { basePath: args.basePath }),\n    trustPolicy: args.trustPolicy,\n    ...(args.signature === undefined ? {} : { signature: args.signature }),\n    async body(_signal?: AbortSignal): Promise<string> {\n      if (bodyCache !== null) return bodyCache;\n      if (bodyPromise === null) {\n        bodyPromise = args.bodyLoader().then((value) => {\n          bodyCache = value;\n          return value;\n        });\n      }\n      return bodyPromise;\n    },\n    async resources(signal?: AbortSignal): Promise<ReadonlyArray<SkillResource>> {\n      if (resourcesCache !== null) return resourcesCache;\n      if (resourcesPromise === null) {\n        resourcesPromise = args.resourceLoader(signal).then((value) => {\n          resourcesCache = value;\n          return value;\n        });\n      }\n      return resourcesPromise;\n    },\n    tools(): ReadonlyArray<InlineSkillTool> {\n      return tools;\n    },\n    toolDeclarations(): ReadonlyArray<SkillToolDeclaration> {\n      return toolDeclarations;\n    },\n    diagnostics(): ReadonlyArray<FrontmatterDiagnostic> {\n      return args.diagnostics;\n    },\n  } satisfies Skill);\n}\n\nfunction describeSource(source: SkillSource): string {\n  switch (source.kind) {\n    case 'folder':\n      return `folder:${source.path}`;\n    case 'npm-package':\n      return source.version === undefined\n        ? `npm:${source.packageName}`\n        : `npm:${source.packageName}@${source.version}`;\n    case 'git-repo':\n      return source.ref === undefined ? `git:${source.url}` : `git:${source.url}@${source.ref}`;\n    case 'inline':\n      return 'inline';\n    default: {\n      const exhaustive: never = source;\n      void exhaustive;\n      return 'unknown';\n    }\n  }\n}\n\nfunction extractTrustLevel(source: SkillSource): SkillsTrustLevel | undefined {\n  if (source.kind === 'npm-package' || source.kind === 'git-repo' || source.kind === 'folder')\n    return source.trustLevel;\n  return undefined;\n}\n\n/**\n * Cap a folder skill's self-declared trust level. A directory on disk —\n * possibly downloaded from the internet — cannot self-promote to a trusted\n * tier without an operator override (RP-9): `trusted` /\n * `trusted-with-scripts` collapse to `'unknown'` (sandbox forced, signature\n * optional, outputs taint-marked), while `untrusted` / `unknown` pass\n * through unchanged.\n */\nfunction capSelfDeclaredTrust(level: SkillsTrustLevel): SkillsTrustLevel {\n  return level === 'trusted' || level === 'trusted-with-scripts' ? 'unknown' : level;\n}\n\n/**\n * Translate the loader's four-valued trust level into the three-\n * valued trust level the supply-chain installer expects.\n *\n * The 'unknown' value collapses to 'untrusted' so the supply-chain\n * resolver picks the strict signature + `--ignore-scripts` policy.\n * The loader keeps the original 'unknown' on the skill's metadata\n * record so the runtime sandbox tier resolver continues to apply\n * the correct policy.\n */\nfunction coerceForSupplyChain(\n  level: SkillsTrustLevel,\n): 'trusted' | 'trusted-with-scripts' | 'untrusted' {\n  if (level === 'unknown') return 'untrusted';\n  return level;\n}\n\nfunction guessMediaType(path: string): string | undefined {\n  const ext = extname(path).toLowerCase();\n  return DEFAULT_MEDIA_TYPES[ext];\n}\n\n/**\n * Required handoff-filter declaration helper. Returns the typed\n * declaration the loader parsed from frontmatter; throws\n * {@link InputFilterRequiredError} when the skill is untrusted and the\n * field is missing. Used by the agent runtime in Phase 12 right\n * before instantiating an untrusted skill's sub-agent.\n *\n * @stable\n */\nexport function requireHandoffInputFilter(metadata: SkillMetadata): HandoffInputFilterDeclaration {\n  if (metadata.graphorinHandoffInputFilter !== undefined) {\n    if (\n      metadata.graphorinTrustLevel === 'untrusted' &&\n      metadata.graphorinHandoffInputFilter.kind === 'full'\n    ) {\n      // ADR-040: `full` is rejected for untrusted skills regardless\n      // of declaration. Fall back to the bounded default.\n      return Object.freeze({ kind: 'lastUser' });\n    }\n    return metadata.graphorinHandoffInputFilter;\n  }\n  if (metadata.graphorinTrustLevel === 'untrusted') {\n    throw new InputFilterRequiredError(metadata.name);\n  }\n  // `'unknown'` skills require an explicit declaration too — default-\n  // deny posture per Phase 08. Trusted skills inherit the framework's\n  // bounded `lastN(10)` default.\n  if (metadata.graphorinTrustLevel === 'unknown') {\n    throw new InputFilterRequiredError(metadata.name);\n  }\n  return Object.freeze({ kind: 'lastN', n: 10 });\n}\n\ntype Mutable<T> = { -readonly [K in keyof T]: T[K] };\n"],"mappings":"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"}

package/dist/migration/index.d.ts

@@ -0,0 +1,62 @@
+//#region src/migration/index.d.ts
+/**
+ * `migrate-frontmatter` — idempotent rewrite helper that migrates
+ * legacy `graphorin-*` frontmatter fields onto their upstream
+ * equivalents per the `deprecate-graphorin-prefix` mappings recorded
+ * in the bundled spec snapshot.
+ *
+ * The function is dry-run by default — callers must opt in to
+ * persisting the rewritten bytes. The CLI binary in Phase 15 wraps
+ * this surface; the library is exposed here so other tooling can
+ * reuse it.
+ *
+ * @packageDocumentation
+ */
+/** A single rewrite the migrator applied (or would apply in a dry-run). */
+interface MigrationRewrite {
+  readonly fromField: string;
+  readonly toField: string;
+  readonly reason: 'deprecate-graphorin-prefix' | 'co-exist-noop' | 'graphorin-only-noop';
+  readonly applied: boolean;
+}
+/** Result of a single SKILL.md migration. */
+interface MigrationResult {
+  readonly skillId: string;
+  readonly rewrites: ReadonlyArray<MigrationRewrite>;
+  readonly originalSkillMd: string;
+  readonly migratedSkillMd: string;
+  readonly changed: boolean;
+}
+/** Options accepted by {@link migrateFrontmatter}. */
+interface MigrateFrontmatterOptions {
+  /** Identifier used in audit / error messages. Defaults to `'<inline>'`. */
+  readonly skillId?: string;
+  /**
+   * When `true`, rewrites are applied to the returned `migratedSkillMd`.
+   * When `false` (default), `migratedSkillMd === originalSkillMd` and
+   * the function operates as a dry-run report.
+   */
+  readonly apply?: boolean;
+}
+/**
+ * Migrate the bundled `deprecate-graphorin-prefix` mappings on a
+ * single SKILL.md. The function is idempotent: re-running it on an
+ * already-migrated SKILL.md returns `changed: false` and an empty
+ * `rewrites` array.
+ *
+ * @stable
+ */
+declare function migrateFrontmatter(skillMd: string, options?: MigrateFrontmatterOptions): MigrationResult;
+/**
+ * Stable key ordering: Anthropic-base fields first (in their snapshot
+ * insertion order), then the `metadata` bucket, then the
+ * `graphorin-*` fields, then anything else. The migrator emits in
+ * this order so re-running the migrator on the same input yields
+ * identical bytes (idempotence).
+ *
+ * @stable
+ */
+declare function sortKeysAnthropicFirst(frontmatter: Record<string, unknown>): Record<string, unknown>;
+//#endregion
+export { MigrateFrontmatterOptions, MigrationResult, MigrationRewrite, migrateFrontmatter, sortKeysAnthropicFirst };
+//# sourceMappingURL=index.d.ts.map

package/dist/migration/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../../src/migration/index.ts"],"sourcesContent":[],"mappings":";;AAqBA;AAQA;AASA;AAmBA;AAiHA;;;;;;;;;UArJiB,gBAAA;;;;;;;UAQA,eAAA;;qBAEI,cAAc;;;;;;UAOlB,yBAAA;;;;;;;;;;;;;;;;;;iBAmBD,kBAAA,4BAEL,4BACR;;;;;;;;;;iBA8Ga,sBAAA,cACD,0BACZ"}