@orion-agents/orion-code 0.1.9 → 0.2.2

package/dist/runtime/skills/filesystem-skill-provider.js

@@ -0,0 +1,829 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilesystemSkillProviderV1 = exports.FilesystemSkillProviderError = exports.DEFAULT_FILESYSTEM_SKILL_PROVIDER_ID = exports.FILESYSTEM_SKILL_PROVIDER_VERSION = void 0;
+exports.createFilesystemSkillRootsV1 = createFilesystemSkillRootsV1;
+exports.createFilesystemSkillProviderV1 = createFilesystemSkillProviderV1;
+exports.createProductionFilesystemSkillProviderV1 = createProductionFilesystemSkillProviderV1;
+const buffer_1 = require("buffer");
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const os_1 = require("os");
+const path_1 = require("path");
+const js_yaml_1 = require("js-yaml");
+const paths_1 = require("../../product/paths");
+const canonical_1 = require("../protocol/canonical");
+const types_1 = require("./types");
+exports.FILESYSTEM_SKILL_PROVIDER_VERSION = 1;
+exports.DEFAULT_FILESYSTEM_SKILL_PROVIDER_ID = 'filesystem-skills-v1';
+const SKILL_FILE_NAME = 'SKILL.md';
+const DEFAULT_MAX_FRONTMATTER_BYTES = 16 * 1024;
+const DEFAULT_MAX_DEFINITION_BYTES = 2 * 1024 * 1024;
+const DEFAULT_MAX_RESOURCE_BYTES = 16 * 1024 * 1024;
+const DEFAULT_MAX_SKILLS = 2048;
+const DEFAULT_MAX_RESOURCE_FILES = 2048;
+const DEFAULT_MAX_WATCH_PATHS = 1024;
+const DEFAULT_WATCH_DEBOUNCE_MS = 25;
+const FRONTMATTER_CHUNK_BYTES = 512;
+const OMITTED_RESOURCE_NAMES = new Set(['.DS_Store']);
+const OMITTED_RESOURCE_DIRECTORIES = new Set(['.git', 'node_modules']);
+class FilesystemSkillProviderError extends Error {
+    constructor(message) {
+        super(message);
+        this.code = 'ORION_FILESYSTEM_SKILL_PROVIDER_ERROR';
+        this.name = 'FilesystemSkillProviderError';
+    }
+}
+exports.FilesystemSkillProviderError = FilesystemSkillProviderError;
+/**
+ * Descriptor-first provider for Orion's builtin, user, configured, and project roots.
+ * list() reads only bounded frontmatter prefixes; bodies/resources are selection-time IO.
+ */
+class FilesystemSkillProviderV1 {
+    constructor(options) {
+        this.version = exports.FILESYSTEM_SKILL_PROVIDER_VERSION;
+        this.listeners = new Set();
+        this.watchers = new Map();
+        this.records = new Map();
+        this.resourceManifests = new Map();
+        this.mutableStats = {
+            catalogScans: 0,
+            rootsObserved: 0,
+            skillFilesObserved: 0,
+            frontmatterPrefixReads: 0,
+            frontmatterPrefixBytes: 0,
+            definitionReads: 0,
+            definitionBytes: 0,
+            resourceReads: 0,
+            resourceBytes: 0,
+            unsafeEntriesRejected: 0,
+            incompleteObservations: 0,
+            watchInvalidations: 0,
+            watchErrors: 0,
+        };
+        this.id = normalizeIdentifier(options.id ?? exports.DEFAULT_FILESYSTEM_SKILL_PROVIDER_ID, 'Provider id');
+        this.roots = normalizeRoots(options.roots);
+        this.watchEnabled = options.watch !== false;
+        this.watchFactory = options.watchFactory ?? defaultWatchFactory;
+        this.watchDebounceMs = integerOption(options.watchDebounceMs ?? DEFAULT_WATCH_DEBOUNCE_MS, 'watchDebounceMs', true);
+        this.maxFrontmatterBytes = integerOption(options.maxFrontmatterBytes ?? DEFAULT_MAX_FRONTMATTER_BYTES, 'maxFrontmatterBytes');
+        this.maxDefinitionBytes = integerOption(options.maxDefinitionBytes ?? DEFAULT_MAX_DEFINITION_BYTES, 'maxDefinitionBytes');
+        this.maxResourceBytes = integerOption(options.maxResourceBytes ?? DEFAULT_MAX_RESOURCE_BYTES, 'maxResourceBytes');
+        this.maxSkills = integerOption(options.maxSkills ?? DEFAULT_MAX_SKILLS, 'maxSkills');
+        this.maxResourceFiles = integerOption(options.maxResourceFiles ?? DEFAULT_MAX_RESOURCE_FILES, 'maxResourceFiles');
+        this.maxWatchPaths = integerOption(options.maxWatchPaths ?? DEFAULT_MAX_WATCH_PATHS, 'maxWatchPaths');
+    }
+    async list(scope, signal) {
+        throwIfAborted(signal);
+        this.mutableStats.catalogScans++;
+        const allowed = new Set(scope.sourceScopeOrder ?? this.roots.map(root => root.sourceScope));
+        const scans = [];
+        let skillCount = 0;
+        for (const root of this.roots.filter(item => allowed.has(item.sourceScope))) {
+            throwIfAborted(signal);
+            const remaining = this.maxSkills - skillCount;
+            if (remaining <= 0) {
+                scans.push(emptyScan(root, 'incomplete', false));
+                continue;
+            }
+            const scan = await this.scanRoot(root, remaining, signal);
+            scans.push(scan);
+            skillCount += scan.records.length;
+        }
+        const records = scans
+            .flatMap(scan => scan.records)
+            .sort((left, right) => left.descriptor.name.localeCompare(right.descriptor.name) ||
+            left.descriptor.id.localeCompare(right.descriptor.id));
+        const next = new Map();
+        let collision = false;
+        for (const record of records) {
+            if (next.has(record.descriptor.id)) {
+                collision = true;
+                continue;
+            }
+            next.set(record.descriptor.id, record);
+        }
+        this.records.clear();
+        for (const [id, record] of next)
+            this.records.set(id, record);
+        this.resourceManifests.clear();
+        const complete = scans.every(scan => scan.complete) && !collision;
+        if (!complete)
+            this.mutableStats.incompleteObservations++;
+        const descriptors = Object.freeze([...next.values()].map(record => record.descriptor));
+        const rootReceipts = scans.map(scan => scan.receipt).sort(compareRootReceipts);
+        const digest = (0, canonical_1.digestRuntimeValue)({
+            version: exports.FILESYSTEM_SKILL_PROVIDER_VERSION,
+            providerId: this.id,
+            complete,
+            roots: rootReceipts,
+            descriptors,
+        });
+        const observation = deepFreeze({
+            version: types_1.LAZY_SKILL_RUNTIME_VERSION,
+            providerId: this.id,
+            digest,
+            complete,
+            descriptors,
+        });
+        this.reconcileWatchers([
+            ...this.roots.map(root => root.path),
+            ...scans.flatMap(scan => scan.watchPaths),
+        ]);
+        return observation;
+    }
+    async get(id, signal) {
+        throwIfAborted(signal);
+        const record = this.records.get(id);
+        if (!record)
+            return undefined;
+        const currentPath = await containedRealPath(record.skillFileRealPath, record.skillDirectoryRealPath, record.rootRealPath);
+        const read = await readBoundedFile(currentPath, this.maxDefinitionBytes, signal, 'Skill definition');
+        if (read.revision.digest !== record.skillFileRevision.digest) {
+            throw new FilesystemSkillProviderError(`Skill ${id} changed after catalog observation.`);
+        }
+        this.mutableStats.definitionReads++;
+        this.mutableStats.definitionBytes += read.buffer.byteLength;
+        const resources = await this.buildResourceManifest(record, signal);
+        const afterManifest = revisionFromStats(await (0, promises_1.stat)(currentPath, { bigint: true }));
+        if (afterManifest.digest !== record.skillFileRevision.digest) {
+            throw new FilesystemSkillProviderError(`Skill ${id} changed while loading its manifest.`);
+        }
+        this.resourceManifests.set(id, new Map(resources.map(resource => [resource.descriptor.path, resource])));
+        return deepFreeze({
+            ...record.descriptor,
+            body: definitionBody(read.buffer.toString('utf8')),
+            resourceManifest: resources.map(resource => resource.descriptor),
+        });
+    }
+    async getResource(id, path, signal) {
+        throwIfAborted(signal);
+        const normalizedPath = normalizeResourcePath(path);
+        const record = this.records.get(id);
+        const resource = this.resourceManifests.get(id)?.get(normalizedPath);
+        if (!record || !resource) {
+            throw new FilesystemSkillProviderError(`Resource ${normalizedPath} is not in the selected manifest for Skill ${id}.`);
+        }
+        const currentPath = await containedRealPath(resource.realPath, record.skillDirectoryRealPath, record.rootRealPath);
+        const read = await readBoundedFile(currentPath, this.maxResourceBytes, signal, `Skill resource ${normalizedPath}`);
+        if (read.revision.digest !== resource.revision.digest) {
+            throw new FilesystemSkillProviderError(`Skill resource changed after manifest capture: ${id}/${normalizedPath}`);
+        }
+        this.mutableStats.resourceReads++;
+        this.mutableStats.resourceBytes += read.buffer.byteLength;
+        const mediaType = resource.descriptor.mediaType;
+        return Object.freeze({
+            skillId: id,
+            path: normalizedPath,
+            digest: resource.descriptor.digest,
+            content: isTextMediaType(mediaType)
+                ? read.buffer.toString('utf8')
+                : new Uint8Array(read.buffer).slice(),
+            ...(mediaType ? { mediaType } : {}),
+        });
+    }
+    subscribe(invalidate, signal) {
+        if (signal.aborted)
+            return Object.freeze({ dispose: () => undefined });
+        this.listeners.add(invalidate);
+        const onAbort = () => {
+            void subscription.dispose();
+        };
+        const subscription = {
+            dispose: () => {
+                signal.removeEventListener('abort', onAbort);
+                this.listeners.delete(invalidate);
+                if (this.listeners.size === 0)
+                    this.closeWatchers();
+            },
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        this.reconcileWatchers(this.roots.map(root => root.path));
+        return subscription;
+    }
+    stats() {
+        return Object.freeze({
+            version: exports.FILESYSTEM_SKILL_PROVIDER_VERSION,
+            ...this.mutableStats,
+            activeWatchers: this.watchers.size,
+        });
+    }
+    async scanRoot(root, remaining, signal) {
+        this.mutableStats.rootsObserved++;
+        try {
+            const rootRealPath = await (0, promises_1.realpath)(root.path);
+            const rootStats = await (0, promises_1.stat)(rootRealPath);
+            if (!rootStats.isDirectory() && !rootStats.isFile()) {
+                return emptyScan(root, 'incomplete', false);
+            }
+            const trustedRoot = rootStats.isFile() ? (0, path_1.dirname)(rootRealPath) : rootRealPath;
+            const candidates = await skillCandidates(rootRealPath, rootStats.isFile(), remaining + 1, signal);
+            const records = [];
+            const watchPaths = new Set([rootStats.isFile() ? (0, path_1.dirname)(root.path) : root.path]);
+            let complete = true;
+            for (const candidate of candidates) {
+                throwIfAborted(signal);
+                if (records.length >= remaining) {
+                    complete = false;
+                    break;
+                }
+                const record = await this.observeSkill(root, trustedRoot, candidate, signal);
+                if (!record) {
+                    complete = false;
+                    continue;
+                }
+                if (!record.descriptorComplete)
+                    complete = false;
+                records.push(record);
+                watchPaths.add(record.skillDirectoryRealPath);
+            }
+            return {
+                records,
+                receipt: {
+                    pathDigest: root.pathDigest,
+                    sourceScope: root.sourceScope,
+                    state: complete ? 'observed' : 'incomplete',
+                    skillCount: records.length,
+                },
+                watchPaths: [...watchPaths],
+                complete,
+            };
+        }
+        catch (error) {
+            return isMissing(error)
+                ? emptyScan(root, 'missing', true)
+                : emptyScan(root, 'incomplete', false);
+        }
+    }
+    async observeSkill(root, rootRealPath, candidate, signal) {
+        try {
+            const skillFileRealPath = await (0, promises_1.realpath)(candidate);
+            const skillDirectoryRealPath = (0, path_1.dirname)(skillFileRealPath);
+            if (!containsPath(rootRealPath, skillDirectoryRealPath) ||
+                !containsPath(skillDirectoryRealPath, skillFileRealPath)) {
+                this.mutableStats.unsafeEntriesRejected++;
+                return undefined;
+            }
+            const frontmatter = await readFrontmatterPrefix(skillFileRealPath, this.maxFrontmatterBytes, this.maxDefinitionBytes, signal, this.mutableStats);
+            const revision = frontmatter.revision;
+            const fallbackName = normalizeSkillName((0, path_1.basename)(skillDirectoryRealPath));
+            const name = stringValue(frontmatter.metadata.name) || fallbackName;
+            const requestedCapabilities = normalizeStringList(frontmatter.metadata.requestedCapabilities ??
+                frontmatter.metadata.capabilities ??
+                frontmatter.metadata.tools);
+            const pathIdentity = (0, canonical_1.digestRuntimeValue)({
+                root: root.pathDigest,
+                relativePath: toPortablePath((0, path_1.relative)(rootRealPath, skillDirectoryRealPath)),
+            });
+            const descriptorBase = {
+                id: `filesystem:${root.sourceScope}:${pathIdentity.slice(0, 24)}`,
+                name: normalizeIdentifier(name, `Skill name in ${SKILL_FILE_NAME}`),
+                description: stringValue(frontmatter.metadata.description).slice(0, 240),
+                providerId: this.id,
+                sourceScope: root.sourceScope,
+                modelInvocable: booleanValue(frontmatter.metadata.modelInvocable ?? frontmatter.metadata['model-invocable'], !booleanValue(frontmatter.metadata['disable-model-invocation'], false)),
+                userInvocable: booleanValue(frontmatter.metadata.userInvocable ?? frontmatter.metadata['user-invocable'], true),
+                requestedCapabilities,
+            };
+            const digest = (0, canonical_1.digestRuntimeValue)({
+                version: exports.FILESYSTEM_SKILL_PROVIDER_VERSION,
+                descriptor: descriptorBase,
+                skillFileRevision: revision.digest,
+                frontmatterDigest: frontmatter.digest,
+            });
+            this.mutableStats.skillFilesObserved++;
+            return {
+                descriptor: deepFreeze({ ...descriptorBase, digest }),
+                descriptorComplete: frontmatter.complete,
+                rootRealPath,
+                skillDirectoryRealPath,
+                skillFileRealPath,
+                skillFileRevision: revision,
+            };
+        }
+        catch (error) {
+            if (!isMissing(error))
+                this.mutableStats.unsafeEntriesRejected++;
+            return undefined;
+        }
+    }
+    async buildResourceManifest(record, signal) {
+        const resources = [];
+        const pending = [record.skillDirectoryRealPath];
+        let directoriesObserved = 0;
+        while (pending.length > 0) {
+            throwIfAborted(signal);
+            directoriesObserved++;
+            if (directoriesObserved > this.maxResourceFiles) {
+                throw new FilesystemSkillProviderError(`Skill ${record.descriptor.id} exceeds the resource directory limit.`);
+            }
+            const directory = pending.pop();
+            const entries = await (0, promises_1.readdir)(directory, { withFileTypes: true });
+            entries.sort((left, right) => left.name.localeCompare(right.name));
+            for (const entry of entries) {
+                throwIfAborted(signal);
+                if (entry.name === SKILL_FILE_NAME || OMITTED_RESOURCE_NAMES.has(entry.name))
+                    continue;
+                if (entry.isDirectory()) {
+                    if (!OMITTED_RESOURCE_DIRECTORIES.has(entry.name))
+                        pending.push((0, path_1.join)(directory, entry.name));
+                    continue;
+                }
+                if (!entry.isFile()) {
+                    this.mutableStats.unsafeEntriesRejected++;
+                    continue;
+                }
+                if (resources.length >= this.maxResourceFiles) {
+                    throw new FilesystemSkillProviderError(`Skill ${record.descriptor.id} exceeds the resource manifest limit.`);
+                }
+                const resourceRealPath = await containedRealPath((0, path_1.join)(directory, entry.name), record.skillDirectoryRealPath, record.rootRealPath);
+                const resourceStats = await (0, promises_1.stat)(resourceRealPath, { bigint: true });
+                if (!resourceStats.isFile())
+                    continue;
+                const revision = revisionFromStats(resourceStats);
+                const path = normalizeResourcePath(toPortablePath((0, path_1.relative)(record.skillDirectoryRealPath, resourceRealPath)));
+                const mediaType = mediaTypeFor(path);
+                resources.push({
+                    realPath: resourceRealPath,
+                    revision,
+                    descriptor: deepFreeze({
+                        path,
+                        digest: (0, canonical_1.digestRuntimeValue)({
+                            version: exports.FILESYSTEM_SKILL_PROVIDER_VERSION,
+                            path,
+                            revision: revision.digest,
+                        }),
+                        bytes: revision.bytes,
+                        ...(mediaType ? { mediaType } : {}),
+                    }),
+                });
+            }
+        }
+        return Object.freeze(resources.sort((left, right) => left.descriptor.path.localeCompare(right.descriptor.path)));
+    }
+    reconcileWatchers(paths) {
+        if (!this.watchEnabled || this.listeners.size === 0)
+            return;
+        const desired = [
+            ...new Set(paths
+                .map(path => nearestWatchablePath(path))
+                .filter((path) => Boolean(path))),
+        ]
+            .sort()
+            .slice(0, this.maxWatchPaths);
+        for (const [path, watcher] of this.watchers) {
+            if (desired.includes(path))
+                continue;
+            watcher.close();
+            this.watchers.delete(path);
+        }
+        for (const path of desired) {
+            if (this.watchers.has(path))
+                continue;
+            try {
+                this.watchers.set(path, this.watchFactory(path, event => this.scheduleInvalidation(event)));
+            }
+            catch {
+                this.mutableStats.watchErrors++;
+            }
+        }
+    }
+    scheduleInvalidation(event) {
+        if (this.watchDebounceMs === 0)
+            return this.emitInvalidation(event);
+        if (this.watchTimer)
+            clearTimeout(this.watchTimer);
+        this.watchTimer = setTimeout(() => this.emitInvalidation(event), this.watchDebounceMs);
+        this.watchTimer.unref?.();
+    }
+    emitInvalidation(event) {
+        if (this.watchTimer)
+            clearTimeout(this.watchTimer);
+        this.watchTimer = undefined;
+        this.mutableStats.watchInvalidations++;
+        this.records.clear();
+        this.resourceManifests.clear();
+        const value = Object.freeze({
+            providerId: this.id,
+            reason: `filesystem_change:${event || 'unknown'}`,
+        });
+        for (const listener of this.listeners)
+            listener(value);
+    }
+    closeWatchers() {
+        if (this.watchTimer)
+            clearTimeout(this.watchTimer);
+        this.watchTimer = undefined;
+        for (const watcher of this.watchers.values())
+            watcher.close();
+        this.watchers.clear();
+    }
+}
+exports.FilesystemSkillProviderV1 = FilesystemSkillProviderV1;
+function createFilesystemSkillRootsV1(options) {
+    const cwd = resolveExpandedPath(options.cwd, process.cwd());
+    const configHome = resolveExpandedPath(options.configHome ?? (0, paths_1.getConfigHome)(), cwd);
+    const builtinRoot = resolveExpandedPath(options.builtinRoot ?? defaultBuiltinRoot(), cwd);
+    return Object.freeze([
+        { path: builtinRoot, sourceScope: 'builtin' },
+        { path: (0, path_1.join)(configHome, 'skills'), sourceScope: 'user' },
+        ...(options.configuredPaths ?? []).map(path => ({
+            path: resolveExpandedPath(path, cwd),
+            sourceScope: 'configured',
+        })),
+        { path: (0, path_1.join)(cwd, '.orion-code', 'skills'), sourceScope: 'project' },
+    ]);
+}
+function createFilesystemSkillProviderV1(options) {
+    return new FilesystemSkillProviderV1(options);
+}
+function createProductionFilesystemSkillProviderV1(options) {
+    const { cwd, configuredPaths, configHome, builtinRoot, ...providerOptions } = options;
+    return new FilesystemSkillProviderV1({
+        ...providerOptions,
+        roots: createFilesystemSkillRootsV1({
+            cwd,
+            ...(configuredPaths ? { configuredPaths } : {}),
+            ...(configHome ? { configHome } : {}),
+            ...(builtinRoot ? { builtinRoot } : {}),
+        }),
+    });
+}
+function normalizeRoots(roots) {
+    const output = [];
+    const seen = new Set();
+    for (const root of roots) {
+        if (!['builtin', 'user', 'configured', 'project'].includes(root.sourceScope)) {
+            throw new FilesystemSkillProviderError(`Unsupported filesystem Skill scope: ${root.sourceScope}`);
+        }
+        const path = resolveExpandedPath(root.path, process.cwd());
+        const key = `${root.sourceScope}\u0000${path}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        output.push(Object.freeze({
+            path,
+            sourceScope: root.sourceScope,
+            pathDigest: (0, canonical_1.digestRuntimeValue)({ path, sourceScope: root.sourceScope }),
+        }));
+    }
+    return Object.freeze(output.sort((left, right) => left.sourceScope.localeCompare(right.sourceScope) || left.path.localeCompare(right.path)));
+}
+async function skillCandidates(rootRealPath, rootIsFile, limit, signal) {
+    if (rootIsFile) {
+        return (0, path_1.basename)(rootRealPath).toLowerCase() === SKILL_FILE_NAME.toLowerCase()
+            ? [rootRealPath]
+            : [];
+    }
+    const direct = (0, path_1.join)(rootRealPath, SKILL_FILE_NAME);
+    try {
+        if ((await (0, promises_1.stat)(direct)).isFile())
+            return [direct];
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+    }
+    const entries = await (0, promises_1.readdir)(rootRealPath, { withFileTypes: true });
+    entries.sort((left, right) => left.name.localeCompare(right.name));
+    const candidates = [];
+    for (const entry of entries) {
+        throwIfAborted(signal);
+        const directory = (0, path_1.join)(rootRealPath, entry.name);
+        try {
+            if (!(await (0, promises_1.stat)(directory)).isDirectory())
+                continue;
+            const file = (0, path_1.join)(directory, SKILL_FILE_NAME);
+            if ((await (0, promises_1.stat)(file)).isFile())
+                candidates.push(file);
+            if (candidates.length >= limit)
+                break;
+        }
+        catch (error) {
+            if (!isMissing(error))
+                throw error;
+        }
+    }
+    return candidates;
+}
+async function readFrontmatterPrefix(path, maxBytes, maxDefinitionBytes, signal, stats) {
+    const handle = await openNoFollow(path);
+    stats.frontmatterPrefixReads++;
+    try {
+        const beforeStats = await handle.stat({ bigint: true });
+        if (!beforeStats.isFile()) {
+            throw new FilesystemSkillProviderError('Skill definition is not a regular file.');
+        }
+        const revision = revisionFromStats(beforeStats);
+        if (revision.bytes > maxDefinitionBytes) {
+            throw new FilesystemSkillProviderError(`Skill definition exceeds the ${maxDefinitionBytes} byte limit.`);
+        }
+        const chunks = [];
+        let bytesRead = 0;
+        let parsedResult;
+        while (bytesRead < maxBytes) {
+            throwIfAborted(signal);
+            const size = Math.min(bytesRead === 0 ? 8 : FRONTMATTER_CHUNK_BYTES, maxBytes - bytesRead);
+            const buffer = buffer_1.Buffer.allocUnsafe(size);
+            const result = await handle.read(buffer, 0, size, bytesRead);
+            if (result.bytesRead === 0)
+                break;
+            chunks.push(buffer.subarray(0, result.bytesRead));
+            bytesRead += result.bytesRead;
+            stats.frontmatterPrefixBytes += result.bytesRead;
+            const text = buffer_1.Buffer.concat(chunks)
+                .toString('utf8')
+                .replace(/^\uFEFF/, '');
+            if (!text.startsWith('---\n') && !text.startsWith('---\r\n')) {
+                parsedResult = {
+                    metadata: {},
+                    digest: (0, canonical_1.digestRuntimeValue)({ kind: 'legacy', prefix: text }),
+                    complete: true,
+                };
+                break;
+            }
+            const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+            if (!match)
+                continue;
+            try {
+                const parsed = (0, js_yaml_1.load)(match[1]);
+                const metadata = isRecord(parsed) ? parsed : {};
+                parsedResult = {
+                    metadata,
+                    digest: (0, canonical_1.digestRuntimeValue)({ kind: 'frontmatter', raw: match[1] }),
+                    complete: isRecord(parsed),
+                };
+            }
+            catch {
+                parsedResult = {
+                    metadata: {},
+                    digest: (0, canonical_1.digestRuntimeValue)({ kind: 'invalid-frontmatter', value: match[1] }),
+                    complete: false,
+                };
+            }
+            break;
+        }
+        if (!parsedResult) {
+            const text = buffer_1.Buffer.concat(chunks)
+                .toString('utf8')
+                .replace(/^\uFEFF/, '');
+            const frontmatterStarted = text.startsWith('---\n') || text.startsWith('---\r\n');
+            parsedResult = frontmatterStarted
+                ? {
+                    metadata: {},
+                    digest: (0, canonical_1.digestRuntimeValue)({ kind: 'truncated-frontmatter', maxBytes }),
+                    complete: false,
+                }
+                : {
+                    metadata: {},
+                    digest: (0, canonical_1.digestRuntimeValue)({ kind: 'legacy', prefix: text }),
+                    complete: true,
+                };
+        }
+        const after = revisionFromStats(await handle.stat({ bigint: true }));
+        if (after.digest !== revision.digest) {
+            throw new FilesystemSkillProviderError('Skill definition changed during catalog scan.');
+        }
+        return { ...parsedResult, revision };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function readBoundedFile(path, maxBytes, signal, label) {
+    const handle = await openNoFollow(path);
+    try {
+        const before = await handle.stat({ bigint: true });
+        if (!before.isFile())
+            throw new FilesystemSkillProviderError(`${label} is not a file.`);
+        const revision = revisionFromStats(before);
+        if (revision.bytes > maxBytes) {
+            throw new FilesystemSkillProviderError(`${label} exceeds the ${maxBytes} byte limit.`);
+        }
+        const buffer = buffer_1.Buffer.alloc(revision.bytes);
+        let offset = 0;
+        while (offset < buffer.byteLength) {
+            throwIfAborted(signal);
+            const result = await handle.read(buffer, offset, buffer.byteLength - offset, offset);
+            if (result.bytesRead === 0)
+                break;
+            offset += result.bytesRead;
+        }
+        if (offset !== buffer.byteLength) {
+            throw new FilesystemSkillProviderError(`${label} changed while it was being read.`);
+        }
+        if (revisionFromStats(await handle.stat({ bigint: true })).digest !== revision.digest) {
+            throw new FilesystemSkillProviderError(`${label} changed while it was being read.`);
+        }
+        return { buffer, revision };
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function openNoFollow(path) {
+    const noFollow = typeof fs_1.constants.O_NOFOLLOW === 'number' ? fs_1.constants.O_NOFOLLOW : 0;
+    return (0, promises_1.open)(path, fs_1.constants.O_RDONLY | noFollow);
+}
+async function containedRealPath(path, skillRoot, providerRoot) {
+    const output = await (0, promises_1.realpath)(path);
+    if (!containsPath(skillRoot, output) || !containsPath(providerRoot, output)) {
+        throw new FilesystemSkillProviderError('Skill path escapes its trusted realpath roots.');
+    }
+    return output;
+}
+function revisionFromStats(stats) {
+    if (stats.size > BigInt(Number.MAX_SAFE_INTEGER)) {
+        throw new FilesystemSkillProviderError('Skill file size exceeds the safe integer range.');
+    }
+    return Object.freeze({
+        bytes: Number(stats.size),
+        digest: (0, canonical_1.digestRuntimeValue)({
+            dev: stats.dev.toString(),
+            ino: stats.ino.toString(),
+            size: stats.size.toString(),
+            mtimeNs: stats.mtimeNs.toString(),
+            ctimeNs: stats.ctimeNs.toString(),
+        }),
+    });
+}
+function definitionBody(content) {
+    const normalized = content.replace(/^\uFEFF/, '');
+    const match = normalized.match(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/);
+    return match ? normalized.slice(match[0].length).trim() : normalized.trim();
+}
+function normalizeResourcePath(path) {
+    const normalized = path.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+    if (!normalized ||
+        normalized.startsWith('/') ||
+        /^[a-z]:\//i.test(normalized) ||
+        normalized.split('/').some(segment => segment === '..' || segment === '' || segment === '.')) {
+        throw new FilesystemSkillProviderError(`Skill resource path must be a contained relative path: ${path}`);
+    }
+    return normalized;
+}
+function containsPath(root, target) {
+    const result = (0, path_1.relative)(root, target);
+    return (result === '' || (!result.startsWith(`..${path_1.sep}`) && result !== '..' && !(0, path_1.isAbsolute)(result)));
+}
+function normalizeIdentifier(value, label) {
+    const normalized = value.trim();
+    if (!normalized || /[\u0000-\u001f\u007f]/.test(normalized)) {
+        throw new FilesystemSkillProviderError(`${label} must be non-empty and contain no control characters.`);
+    }
+    return normalized;
+}
+function normalizeSkillName(value) {
+    return (value
+        .trim()
+        .replace(/\.md$/i, '')
+        .replace(/([a-z0-9])([A-Z])/g, '$1-$2')
+        .replace(/[^\p{L}\p{N}]+/gu, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase() || 'skill');
+}
+function normalizeStringList(value) {
+    const values = Array.isArray(value) ? value : typeof value === 'string' ? value.split(',') : [];
+    return Object.freeze([
+        ...new Set(values
+            .filter(item => typeof item === 'string')
+            .map(item => item.trim())
+            .filter(Boolean)),
+    ].sort());
+}
+function booleanValue(value, fallback) {
+    return typeof value === 'boolean' ? value : fallback;
+}
+function stringValue(value) {
+    return typeof value === 'string' ? value.trim() : '';
+}
+function resolveExpandedPath(value, cwd) {
+    const trimmed = value.trim();
+    if (!trimmed || trimmed.includes('\u0000')) {
+        throw new FilesystemSkillProviderError('Filesystem Skill root must not be empty.');
+    }
+    const expanded = trimmed === '~'
+        ? (0, os_1.homedir)()
+        : trimmed.startsWith('~/')
+            ? (0, path_1.join)((0, os_1.homedir)(), trimmed.slice(2))
+            : trimmed;
+    return (0, path_1.resolve)(cwd, expanded);
+}
+function defaultBuiltinRoot() {
+    return (0, path_1.resolve)(__dirname, '../../skills/builtin');
+}
+function defaultWatchFactory(path, invalidate) {
+    let watcher;
+    try {
+        watcher = (0, fs_1.watch)(path, { recursive: true, persistent: false }, event => invalidate(event));
+    }
+    catch {
+        watcher = (0, fs_1.watch)(path, { persistent: false }, event => invalidate(event));
+    }
+    return { close: () => watcher.close() };
+}
+function nearestWatchablePath(path) {
+    let candidate = (0, path_1.resolve)(path);
+    // At most the direct parent: never turn a missing project Skill directory into
+    // a recursive watch of the whole workspace.
+    for (let depth = 0; depth <= 1; depth++) {
+        if ((0, fs_1.existsSync)(candidate)) {
+            try {
+                return (0, fs_1.statSync)(candidate).isDirectory() ? candidate : (0, path_1.dirname)(candidate);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        const parent = (0, path_1.dirname)(candidate);
+        if (parent === candidate)
+            return undefined;
+        candidate = parent;
+    }
+    return undefined;
+}
+function emptyScan(root, state, complete) {
+    return {
+        records: [],
+        receipt: {
+            pathDigest: root.pathDigest,
+            sourceScope: root.sourceScope,
+            state,
+            skillCount: 0,
+        },
+        watchPaths: [],
+        complete,
+    };
+}
+function compareRootReceipts(left, right) {
+    return (left.sourceScope.localeCompare(right.sourceScope) ||
+        left.pathDigest.localeCompare(right.pathDigest));
+}
+function mediaTypeFor(path) {
+    switch ((0, path_1.extname)(path).toLowerCase()) {
+        case '.md':
+            return 'text/markdown';
+        case '.txt':
+            return 'text/plain';
+        case '.json':
+            return 'application/json';
+        case '.yaml':
+        case '.yml':
+            return 'application/yaml';
+        case '.js':
+        case '.mjs':
+        case '.cjs':
+            return 'text/javascript';
+        case '.ts':
+        case '.tsx':
+            return 'text/typescript';
+        case '.sh':
+            return 'text/x-shellscript';
+        case '.png':
+            return 'image/png';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.svg':
+            return 'image/svg+xml';
+        default:
+            return undefined;
+    }
+}
+function isTextMediaType(mediaType) {
+    return Boolean(mediaType?.startsWith('text/') ||
+        mediaType === 'application/json' ||
+        mediaType === 'application/yaml' ||
+        mediaType === 'image/svg+xml');
+}
+function integerOption(value, label, allowZero = false) {
+    if (!Number.isSafeInteger(value) || value < (allowZero ? 0 : 1)) {
+        throw new FilesystemSkillProviderError(`${label} must be a ${allowZero ? 'non-negative' : 'positive'} safe integer.`);
+    }
+    return value;
+}
+function toPortablePath(path) {
+    return path.split(path_1.sep).join('/');
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isMissing(error) {
+    return isRecord(error) && (error.code === 'ENOENT' || error.code === 'ENOTDIR');
+}
+function throwIfAborted(signal) {
+    if (!signal.aborted)
+        return;
+    throw signal.reason instanceof Error
+        ? signal.reason
+        : new Error(String(signal.reason || 'Filesystem Skill operation aborted.'));
+}
+function deepFreeze(value) {
+    if (value === null || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    if (ArrayBuffer.isView(value))
+        return value;
+    for (const nested of Object.values(value))
+        deepFreeze(nested);
+    return Object.freeze(value);
+}
+//# sourceMappingURL=filesystem-skill-provider.js.map