pi-session-mcp 0.7.1 → 0.8.1

package/dist/setup.js

@@ -8,6 +8,7 @@ import { createMcpStdioLauncher } from "./setup-process.js";
 import { verifyMcpCapabilities } from "./client-adapters/mcp-verifier.js";
 import { PACKAGE_VERSION, readLockfile, readPackageMetadata } from "./package-metadata.js";
 import { DurableOwnershipStore, MemoryOwnershipStore } from "./setup-ownership.js";
+import { FileSetupSkillInstaller } from "./setup-skills.js";
 import { result } from "./setup-result.js";
 export const isSupportedTarget = (target) => target.alias === "pi-session-mcp" &&
     (target.client === "codex" ? target.scope === "user" :
@@ -15,6 +16,8 @@ export const isSupportedTarget = (target) => target.alias === "pi-session-mcp" &
 export class SetupOrchestrator {
     dependencies;
     ownership;
+    /** Apply results that the up-front plan refused: nothing was applied, so no skill is touched. */
+    refusedApplies = new WeakSet();
     constructor(dependencies) {
         this.dependencies = dependencies;
         this.ownership = dependencies.ownership ?? new MemoryOwnershipStore();
@@ -25,14 +28,40 @@ export class SetupOrchestrator {
         if (targets.length !== request.targets.length || targets.length === 0)
             return result(operation, [{ target: { client: "invalid", scope: "invalid", alias: "invalid" }, status: "failed", code: "target_invalid" }], "failed");
         if (operation === "dry-run")
-            return this.plan(targets, this.ownership);
+            return this.withSkills(await this.plan(targets, this.ownership), this.ownership);
         if (operation === "apply")
-            return this.ownership.transaction((ownership) => this.apply(targets, ownership));
+            return this.ownership.transaction(async (ownership) => this.withSkills(await this.apply(targets, ownership), ownership));
         if (operation === "verify")
-            return this.ownership.transaction((ownership) => this.verify(targets, ownership));
+            return this.ownership.transaction(async (ownership) => this.withSkills(await this.verify(targets, ownership), ownership));
         if (operation === "rollback")
-            return this.ownership.transaction((ownership) => this.restore(targets, "rolled_back", ownership));
-        return this.ownership.transaction((ownership) => this.restore(targets, "removed", ownership));
+            return this.ownership.transaction((ownership) => this.restoreWithSkills(targets, "rolled_back", ownership));
+        return this.ownership.transaction((ownership) => this.restoreWithSkills(targets, "removed", ownership));
+    }
+    /** Registration planning gates apply; skill divergence must not block registration. */
+    async withSkills(registrations, ownership) {
+        const skills = this.dependencies.skills;
+        if (!skills || this.refusedApplies.has(registrations))
+            return registrations;
+        const findings = [];
+        for (const finding of registrations.findings) {
+            findings.push(finding);
+            const operation = registrations.operation;
+            const canRun = operation === "dry-run" || operation === "verify" ||
+                (operation === "apply" ? ["ok", "unchanged"].includes(finding.status) : finding.status === "ok");
+            if (canRun)
+                findings.push(...await skills.run(operation, finding.target, ownership));
+        }
+        const failed = findings.some((finding) => ["failed", "unsupported", "divergent"].includes(finding.status));
+        return result(registrations.operation, findings, failed ? "failed" : registrations.status, failed ? 1 : registrations.exitCode);
+    }
+    async restoreWithSkills(targets, success, ownership) {
+        if (!this.dependencies.skills)
+            return this.restore(targets, success, ownership);
+        const findings = [];
+        // Process each removal and its skill before removing another shared registration.
+        for (const target of targets)
+            findings.push(...(await this.withSkills(await this.restore([target], success, ownership), ownership)).findings);
+        return result(success === "removed" ? "remove" : "rollback", findings);
     }
     adapter(t) { return this.dependencies.adapters?.find((a) => a.name === t.client && a.supportedScopes.includes(t.scope)); }
     assertOwnershipHealthy(ownership) { ownership.assertHealthy?.(); }
@@ -84,7 +113,9 @@ export class SetupOrchestrator {
             const findings = plan.findings.map((finding) => finding.status === "divergent" && finding.code === "divergent"
                 ? { ...finding, code: "divergence_requires_replacement" }
                 : finding);
-            return result("apply", findings, "failed");
+            const refused = result("apply", findings, "failed");
+            this.refusedApplies.add(refused);
+            return refused;
         }
         const findings = [];
         for (const target of targets) {
@@ -205,6 +236,17 @@ export class SetupOrchestrator {
                 findings.push({ target, status: "unsupported", code: "client_unsupported" });
                 continue;
             }
+            if (!owned && this.dependencies.skills && await this.safe(() => this.dependencies.skills.owns(target, ownership))) {
+                // Registration removal can finish before skill cleanup (or before a crash). Retry only
+                // for a skill setup still owns, and only after proving the registration is absent; an
+                // unowned live registration stays untouched.
+                const current = await this.safe(() => adapter.inspect(target, this.dependencies.intendedFingerprint));
+                this.assertOwnershipHealthy(ownership);
+                if (current?.state === "absent") {
+                    findings.push({ target, status: "ok", code: success });
+                    continue;
+                }
+            }
             if (!owned || (owned.phase !== "owned" && owned.phase !== "pending")) {
                 findings.push({ target, status: "failed", code: "ownership_unavailable" });
                 continue;
@@ -320,6 +362,7 @@ export async function createProductionSetup(runner, packageRoot, configPath, own
                 return { ok: doctor.ok, code: doctor.ok ? "doctor_ok" : "doctor_failed" };
             },
         },
+        skills: new FileSetupSkillInstaller({ packageRoot, configPath, home: homedir(), cwd: process.cwd() }),
         ownership: new DurableOwnershipStore(ownershipPath, { ...(signal ? { signal } : {}) }),
         intendedFingerprint: await fingerprintFor(referenceTarget),
     };

package/dist/skill-catalog.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A catalog skill that an execution profile selects. The alias is the only public name;
+ * the path stays inside the server and never appears in MCP output, errors or diagnostics.
+ */
+export interface SkillSelection {
+    /** The operator's `skillCatalog` alias. Path-free; it may differ from the skill's own name. */
+    readonly alias: string;
+    /** Absolute path of the selected `SKILL.md`, resolved against the configuration file's directory. */
+    readonly path: string;
+}
+export declare const MAX_SKILL_CATALOG_ENTRIES = 64;
+export declare const MAX_PROFILE_SKILLS = 16;
+export declare const MAX_SKILL_PATH_LENGTH = 4096;
+/** Upper bound for one selected `SKILL.md`, checked before the Pi SDK reads it. */
+export declare const MAX_SKILL_FILE_BYTES: number;
+export declare const SKILL_FILE_NAME = "SKILL.md";
+/** The library skill name of a `builtin:<name>` catalog value; undefined for every other value. */
+export declare function builtinSkillName(value: string): string | undefined;
+/**
+ * Whether a configured catalog value names exactly one local `SKILL.md`: its last path segment
+ * is `SKILL.md`, and it is no URL or other scheme-prefixed source, no `~` home shorthand, no
+ * glob and no Windows-style path. So it can never stand for a directory, a pattern or a
+ * remote source. Relative values are resolved later against the configuration file's directory.
+ * The one scheme-prefixed form accepted is `builtin:<name>`, which names a library skill.
+ */
+export declare function isSkillCatalogPath(value: string): boolean;

package/dist/skill-catalog.js

@@ -0,0 +1,35 @@
+import { BUILTIN_SKILL_PREFIX, SKILL_NAME_PATTERN } from "./skill-library.js";
+export const MAX_SKILL_CATALOG_ENTRIES = 64;
+export const MAX_PROFILE_SKILLS = 16;
+export const MAX_SKILL_PATH_LENGTH = 4096;
+/** Upper bound for one selected `SKILL.md`, checked before the Pi SDK reads it. */
+export const MAX_SKILL_FILE_BYTES = 256 * 1024;
+export const SKILL_FILE_NAME = "SKILL.md";
+/** `npm:`, `git+ssh:`, `https:`, `file:` and any other scheme-prefixed source. */
+const SCHEME_PREFIX = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+const GLOB_CHARACTERS = /[*?[\]{}]/;
+/** The library skill name of a `builtin:<name>` catalog value; undefined for every other value. */
+export function builtinSkillName(value) {
+    if (!value.startsWith(BUILTIN_SKILL_PREFIX))
+        return undefined;
+    const name = value.slice(BUILTIN_SKILL_PREFIX.length);
+    return SKILL_NAME_PATTERN.test(name) ? name : undefined;
+}
+/**
+ * Whether a configured catalog value names exactly one local `SKILL.md`: its last path segment
+ * is `SKILL.md`, and it is no URL or other scheme-prefixed source, no `~` home shorthand, no
+ * glob and no Windows-style path. So it can never stand for a directory, a pattern or a
+ * remote source. Relative values are resolved later against the configuration file's directory.
+ * The one scheme-prefixed form accepted is `builtin:<name>`, which names a library skill.
+ */
+export function isSkillCatalogPath(value) {
+    if (value.length === 0 || value.length > MAX_SKILL_PATH_LENGTH)
+        return false;
+    if (value.includes("\0") || value.includes("\\") || value.startsWith("~"))
+        return false;
+    if (builtinSkillName(value) !== undefined)
+        return true;
+    if (SCHEME_PREFIX.test(value) || GLOB_CHARACTERS.test(value))
+        return false;
+    return value.split("/").at(-1) === SKILL_FILE_NAME;
+}

package/dist/skill-customize.d.ts

@@ -0,0 +1,41 @@
+import { type OverrideLockOptions } from "./override-lock.js";
+import { type SetupResult } from "./setup-result.js";
+import { type ReleasedSkillTree } from "./skill-library.js";
+/**
+ * `--customize-skill <name>`: copies a shipped skill into the operator's override directory as a
+ * starting point, and records the shipped fingerprint it was based on. The operator's files are
+ * never overwritten or edited; a changed original is only reported and acknowledged by moving
+ * the recorded base. Reports carry the skill name and a code, never a path or file content.
+ *
+ * Applying is a cross-process transaction: everything from reading the bases file to replacing it
+ * runs under the kernel lock of `override-lock.ts`, so two runs for different skills cannot lose
+ * each other's base. A dry run takes no lock and writes nothing.
+ */
+export declare const SKILL_BASES_FILE = ".pi-session-mcp-bases.json";
+export declare const MAX_SKILL_BASES_BYTES: number;
+export declare class SkillBasesError extends Error {
+    constructor();
+}
+/** Per skill, a version 2 fingerprint or a legacy (version 1) one that could not be migrated. */
+export type SkillBases = Readonly<Record<string, string>>;
+/** Strictly validated contents of the bases file; an absent file or override directory is an empty record. */
+export declare function readSkillBases(overrideDirectory: string): Promise<SkillBases>;
+export interface SkillCustomizeRequest {
+    readonly name: string;
+    readonly configPath: string;
+    readonly apply: boolean;
+    /** Package root that holds the shipped `skills/` directory; defaults to this package. */
+    readonly packageRoot?: string;
+}
+/** Injection points for tests; production callers pass none. */
+export interface SkillCustomizeDependencies {
+    /** Reference trees that resolve legacy bases; defaults to the released shipped skills. */
+    readonly released?: readonly ReleasedSkillTree[];
+    /** Lock acquisition bound and platform seams. */
+    readonly lock?: OverrideLockOptions;
+    /** Runs while the lock is held, before the bases file is read. */
+    readonly afterLock?: () => Promise<void> | void;
+    /** Runs while the lock is held, after the new bases content is durable and before it replaces the old file. */
+    readonly beforeBasesRename?: () => Promise<void> | void;
+}
+export declare function customizeSkill(request: SkillCustomizeRequest, dependencies?: SkillCustomizeDependencies): Promise<SetupResult>;

package/dist/skill-customize.js

@@ -0,0 +1,268 @@
+import { randomBytes } from "node:crypto";
+import { constants } from "node:fs";
+import { lstat, mkdir, open, readFile, rename, rm, unlink } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { acquireOverrideLock, OverrideLockError } from "./override-lock.js";
+import { result } from "./setup-result.js";
+import { LEGACY_SKILL_TREE_FINGERPRINT_PATTERN, readSkillTree, releasedSkillFingerprint, shippedSkillsDirectory, SKILL_NAME_PATTERN, SKILL_TREE_FINGERPRINT_PATTERN, SkillTreeError, skillOverrideDirectory, } from "./skill-library.js";
+/**
+ * `--customize-skill <name>`: copies a shipped skill into the operator's override directory as a
+ * starting point, and records the shipped fingerprint it was based on. The operator's files are
+ * never overwritten or edited; a changed original is only reported and acknowledged by moving
+ * the recorded base. Reports carry the skill name and a code, never a path or file content.
+ *
+ * Applying is a cross-process transaction: everything from reading the bases file to replacing it
+ * runs under the kernel lock of `override-lock.ts`, so two runs for different skills cannot lose
+ * each other's base. A dry run takes no lock and writes nothing.
+ */
+export const SKILL_BASES_FILE = ".pi-session-mcp-bases.json";
+export const MAX_SKILL_BASES_BYTES = 64 * 1024;
+/** Written by this version; version 1 (0.8.0) holds only legacy fingerprints and is still read. */
+const BASES_SCHEMA_VERSION = 2;
+export class SkillBasesError extends Error {
+    constructor() {
+        super("Skill bases file is not usable");
+        this.name = "SkillBasesError";
+    }
+}
+/** Strictly validated contents of the bases file; an absent file or override directory is an empty record. */
+export async function readSkillBases(overrideDirectory) {
+    const path = join(overrideDirectory, SKILL_BASES_FILE);
+    let text;
+    try {
+        const info = await lstat(path);
+        if (!info.isFile() || info.size > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        const bytes = await readFile(path);
+        if (bytes.length > MAX_SKILL_BASES_BYTES)
+            throw new SkillBasesError();
+        text = bytes.toString("utf8");
+    }
+    catch (error) {
+        if (error instanceof SkillBasesError)
+            throw error;
+        if (typeof error === "object" && error !== null && error.code === "ENOENT")
+            return Object.freeze({});
+        throw new SkillBasesError();
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new SkillBasesError();
+    }
+    if (!isPlainObject(parsed) || Object.keys(parsed).sort().join() !== "bases,schemaVersion")
+        throw new SkillBasesError();
+    const version = parsed.schemaVersion;
+    if (version !== 1 && version !== BASES_SCHEMA_VERSION)
+        throw new SkillBasesError();
+    const bases = parsed.bases;
+    if (!isPlainObject(bases))
+        throw new SkillBasesError();
+    const entries = Object.entries(bases);
+    const validValue = (value) => typeof value === "string" && (LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(value) || (version === BASES_SCHEMA_VERSION && SKILL_TREE_FINGERPRINT_PATTERN.test(value)));
+    if (!entries.every(([name, value]) => SKILL_NAME_PATTERN.test(name) && validValue(value)))
+        throw new SkillBasesError();
+    return Object.freeze(Object.fromEntries(entries));
+}
+function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+async function syncDirectory(path) {
+    const handle = await open(path, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+/**
+ * Atomic replacement: a private temporary file in the same directory, fsynced, then a rename and a
+ * directory fsync. Every provable legacy entry is migrated to its version 2 value on the way; an
+ * entry that no released tree names stays verbatim. A failure before the rename leaves the
+ * previous file untouched.
+ */
+async function writeSkillBases(overrideDirectory, bases, released, beforeRename) {
+    const migrated = Object.entries(bases).map(([name, value]) => [name, LEGACY_SKILL_TREE_FINGERPRINT_PATTERN.test(value) ? releasedSkillFingerprint(name, value, released) ?? value : value]);
+    const sorted = Object.fromEntries(migrated.sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0)));
+    const content = Buffer.from(`${JSON.stringify({ schemaVersion: BASES_SCHEMA_VERSION, bases: sorted })}\n`, "utf8");
+    if (content.length > MAX_SKILL_BASES_BYTES)
+        throw new SkillBasesError();
+    const temporary = join(overrideDirectory, `.${SKILL_BASES_FILE.slice(1)}.${randomBytes(6).toString("hex")}.tmp`);
+    const handle = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+    try {
+        try {
+            await handle.writeFile(content);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await beforeRename?.();
+        await rename(temporary, join(overrideDirectory, SKILL_BASES_FILE));
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    await syncDirectory(overrideDirectory);
+}
+function isMissing(error) {
+    return typeof error === "object" && error !== null && error.code === "ENOENT";
+}
+function report(request, status, code) {
+    // The name is echoed only when it is a valid skill name, so arbitrary input never reaches a report.
+    const alias = SKILL_NAME_PATTERN.test(request.name) ? request.name : "invalid";
+    const target = { client: "skills", scope: "override", alias };
+    const finding = { target, status, code };
+    // A planned change reports `planned` overall, like a registration dry-run.
+    return result(request.apply ? "apply" : "dry-run", [finding], status === "planned" ? "planned" : undefined);
+}
+const OUTDATED = Object.freeze({ kind: "record", planned: "skill_override_outdated", applied: "skill_base_updated" });
+/** Pure with respect to the library: reads the override tree, never changes anything. */
+async function decide(name, overridePath, shipped, bases, released) {
+    try {
+        if (!(await lstat(overridePath)).isDirectory())
+            return { kind: "failed", code: "skill_override_invalid" };
+    }
+    catch (error) {
+        if (!isMissing(error))
+            throw error;
+        return { kind: "copy", planned: "skill_customize_planned", applied: "skill_customized" };
+    }
+    let override;
+    try {
+        override = await readSkillTree(overridePath);
+    }
+    catch (error) {
+        if (error instanceof SkillTreeError)
+            return { kind: "failed", code: "skill_override_invalid" };
+        throw error;
+    }
+    const base = Object.hasOwn(bases, name) ? bases[name] : undefined;
+    // Without a base an identical override is a customization whose bases commit failed earlier.
+    if (base === undefined)
+        return override.fingerprint === shipped.fingerprint ? { kind: "record", planned: "skill_customize_planned", applied: "skill_customized" } : OUTDATED;
+    if (SKILL_TREE_FINGERPRINT_PATTERN.test(base))
+        return base === shipped.fingerprint ? { kind: "current" } : OUTDATED;
+    // A legacy base only names a released original when a trusted reference tree has that value.
+    const original = releasedSkillFingerprint(name, base, released);
+    if (original === undefined)
+        return { kind: "record", planned: "skill_base_unverified", applied: "skill_base_updated" };
+    return original === shipped.fingerprint ? { kind: "record", planned: "skill_base_migration_planned", applied: "skill_base_migrated" } : OUTDATED;
+}
+export async function customizeSkill(request, dependencies = {}) {
+    const done = (status, code) => report(request, status, code);
+    if (!SKILL_NAME_PATTERN.test(request.name))
+        return done("failed", "skill_not_shipped");
+    try {
+        const shippedDirectory = join(shippedSkillsDirectory(request.packageRoot), request.name);
+        let shipped;
+        try {
+            shipped = await readSkillTree(shippedDirectory);
+        }
+        catch (error) {
+            if (error instanceof SkillTreeError && error.code === "skill_tree_missing")
+                return done("failed", "skill_not_shipped");
+            return done("failed", "skill_customize_failed");
+        }
+        const overrideDirectory = skillOverrideDirectory(request.configPath);
+        const overridePath = join(overrideDirectory, request.name);
+        const read = async () => {
+            try {
+                return await readSkillBases(overrideDirectory);
+            }
+            catch (error) {
+                if (error instanceof SkillBasesError)
+                    return undefined;
+                throw error;
+            }
+        };
+        if (!request.apply) {
+            // No lock and no write: the report is a snapshot of what an apply would decide.
+            const bases = await read();
+            if (bases === undefined)
+                return done("failed", "skill_bases_corrupt");
+            const decision = await decide(request.name, overridePath, shipped, bases, dependencies.released);
+            if (decision.kind === "failed")
+                return done("failed", decision.code);
+            return decision.kind === "current" ? done("unchanged", "skill_override_current") : done("planned", decision.planned);
+        }
+        await mkdir(overrideDirectory, { recursive: true, mode: 0o700 });
+        let lock;
+        try {
+            lock = await acquireOverrideLock(overrideDirectory, dependencies.lock);
+        }
+        catch (error) {
+            if (error instanceof OverrideLockError)
+                return done("failed", error.code === "override_lock_busy" ? "skill_customize_lock_busy" : "skill_customize_lock_unavailable");
+            throw error;
+        }
+        try {
+            await dependencies.afterLock?.();
+            // Read only now: a snapshot from before the lock may miss a base another run just wrote.
+            const bases = await read();
+            if (bases === undefined)
+                return done("failed", "skill_bases_corrupt");
+            const decision = await decide(request.name, overridePath, shipped, bases, dependencies.released);
+            if (decision.kind === "failed")
+                return done("failed", decision.code);
+            if (decision.kind === "current")
+                return done("unchanged", "skill_override_current");
+            if (decision.kind === "copy")
+                await copyShippedSkill(shipped.files, overrideDirectory, overridePath, request.name);
+            await writeSkillBases(overrideDirectory, { ...bases, [request.name]: shipped.fingerprint }, dependencies.released, dependencies.beforeBasesRename);
+            return done("ok", decision.applied);
+        }
+        finally {
+            await lock.release();
+        }
+    }
+    catch {
+        return done("failed", "skill_customize_failed");
+    }
+}
+async function copyShippedSkill(files, overrideDirectory, overridePath, name) {
+    const temporary = join(overrideDirectory, `.${name}.${randomBytes(6).toString("hex")}.tmp`);
+    try {
+        await mkdir(temporary, { mode: 0o755 });
+        for (const file of files) {
+            const destination = join(temporary, ...file.path.split("/"));
+            await mkdir(dirname(destination), { recursive: true });
+            const handle = await open(destination, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o644);
+            try {
+                await handle.writeFile(file.bytes);
+                await handle.sync();
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        // Every directory entry of the temporary tree is durable before the rename and the bases commit.
+        const directories = new Set([temporary]);
+        for (const file of files) {
+            let cursor = dirname(join(temporary, ...file.path.split("/")));
+            while (cursor !== temporary) {
+                directories.add(cursor);
+                cursor = dirname(cursor);
+            }
+        }
+        for (const directory of [...directories].sort((left, right) => right.length - left.length))
+            await syncDirectory(directory);
+        // The override must not appear while the copy runs, and an operator's directory is never replaced.
+        if (await lstat(overridePath).then(() => true, (error) => { if (isMissing(error))
+            return false; throw error; }))
+            throw new Error("override appeared");
+        await rename(temporary, overridePath);
+        await syncDirectory(overrideDirectory);
+    }
+    catch (error) {
+        await rm(temporary, { recursive: true, force: true }).catch(() => undefined);
+        throw error;
+    }
+}

package/dist/skill-library.d.ts

@@ -0,0 +1,106 @@
+/**
+ * The skill library: skills shipped in the package's `skills/` directory, and the operator's
+ * override directory `skills/` next to the configuration file. An override with the same name
+ * replaces the shipped skill; a new name adds a skill. Nothing else is searched.
+ */
+/** Agent Skills name rule: lowercase letters and digits in hyphen-separated groups, 1 to 64 characters. */
+export declare const SKILL_NAME_PATTERN: RegExp;
+/** A `skillCatalog` value `builtin:<name>` names a library skill instead of a path. */
+export declare const BUILTIN_SKILL_PREFIX = "builtin:";
+/** Skills for the controlling agent, which setup installs into Claude Code and Codex. */
+export declare const CONTROLLER_SKILLS: readonly string[];
+export declare const MAX_SKILL_TREE_FILES = 32;
+export declare const MAX_SKILL_TREE_BYTES: number;
+/** `dist/`, `.pi-session-mcp-cli/` and `src/` all sit one level below the package root. */
+export declare const PACKAGE_ROOT: string;
+export declare function shippedSkillsDirectory(packageRoot?: string): string;
+/** The override directory belongs to the configuration, never to a workspace or the shell's directory. */
+export declare function skillOverrideDirectory(configPath: string): string;
+export interface LibrarySkill {
+    readonly name: string;
+    readonly source: "override" | "shipped";
+    /** Absolute directory that holds the skill's `SKILL.md`. Internal; never reported. */
+    readonly directory: string;
+}
+export interface LibraryRoots {
+    readonly overrideDirectory: string;
+    readonly packageRoot?: string;
+}
+/** The override wins over the shipped skill of the same name; undefined when neither exists. */
+export declare function resolveLibrarySkill(name: string, roots: LibraryRoots): LibrarySkill | undefined;
+/** The `SKILL.md` a `builtin:<name>` catalog value stands for; a missing skill keeps the shipped location. */
+export declare function builtinSkillPath(name: string, roots: LibraryRoots): string;
+export interface SkillTreeFile {
+    /** Path relative to the skill directory, with `/` separators. */
+    readonly path: string;
+    readonly bytes: Buffer;
+}
+export interface SkillTree {
+    readonly files: readonly SkillTreeFile[];
+    /** Version 2 fingerprint (`v2:` and SHA-256 hex) of the paths and contents; path-free and stable. */
+    readonly fingerprint: string;
+    /**
+     * The version 1 fingerprint that 0.8.0 recorded, only to recognize such records. It is
+     * ambiguous and never proves identity on its own; see `provesLegacyFingerprint`.
+     */
+    readonly legacyFingerprint: string;
+}
+export declare class SkillTreeError extends Error {
+    readonly code: "skill_tree_missing" | "skill_tree_invalid" | "skill_tree_too_large";
+    constructor(code: "skill_tree_missing" | "skill_tree_invalid" | "skill_tree_too_large");
+}
+/** A version 2 skill tree fingerprint as it is stored. */
+export declare const SKILL_TREE_FINGERPRINT_PATTERN: RegExp;
+/** A version 1 fingerprint as 0.8.0 stored it: bare SHA-256 hex. */
+export declare const LEGACY_SKILL_TREE_FINGERPRINT_PATTERN: RegExp;
+/**
+ * Version 2: a domain and version tag, the file count, then per file in byte order of the path
+ * the length-prefixed UTF-8 path and the length-prefixed content. Every field has an explicit
+ * length, so two different trees never share an encoding.
+ */
+export declare function skillTreeFingerprint(files: readonly SkillTreeFile[]): string;
+/**
+ * Version 1, as 0.8.0 computed it: `path NUL content NUL` per file in reading order. File
+ * content may contain NUL bytes, so two different trees can share this value.
+ */
+export declare function legacySkillTreeFingerprint(files: readonly SkillTreeFile[]): string;
+export interface ReleasedSkillTree {
+    readonly name: string;
+    readonly release: string;
+    readonly legacyFingerprint: string;
+    readonly fingerprint: string;
+}
+/**
+ * The shipped skills of every release that recorded version 1 fingerprints (0.8.0 only), as
+ * trusted references for recognizing such records. Computed from the `v0.8.0` tag and checked
+ * against the published npm package.
+ */
+export declare const RELEASED_SKILL_TREES: readonly ReleasedSkillTree[];
+/**
+ * Whether a version 1 fingerprint from a record proves that `candidate` is the tree it names:
+ * a trusted reference, a released shipped tree of this name or one of `references` (such as
+ * the current library tree), has exactly this version 1 fingerprint and is byte-identical to
+ * `candidate` by its version 2 fingerprint. The version 1 fingerprint alone never suffices.
+ */
+export declare function provesLegacyFingerprint(name: string, legacyFingerprint: string, candidate: Pick<SkillTree, "fingerprint">, references?: readonly Pick<SkillTree, "fingerprint" | "legacyFingerprint">[], released?: readonly ReleasedSkillTree[]): boolean;
+/**
+ * The version 2 fingerprint of the released shipped skill that a version 1 fingerprint names,
+ * or undefined. Only released trees qualify: the current shipped tree could share a version 1
+ * fingerprint with an older original without being that original.
+ */
+export declare function releasedSkillFingerprint(name: string, legacyFingerprint: string, released?: readonly ReleasedSkillTree[]): string | undefined;
+export interface ReadSkillTreeOptions {
+    /**
+     * `skip` (default) ignores entries whose name starts with `.`, as for a source tree. `reject`
+     * fails on them, for an installed copy: setup never writes hidden entries, so one there is
+     * operator content that a fingerprint over the visible files would not protect.
+     */
+    readonly hidden?: "skip" | "reject";
+}
+/**
+ * Reads the regular files below a skill directory in a stable order. Entries whose name starts
+ * with `.` are skipped or rejected (see options). A symbolic link or special file inside the
+ * tree, a missing `SKILL.md`, or more than the file and byte limits fail, so the tree can be
+ * copied and compared exactly.
+ */
+export declare function readSkillTree(directory: string, options?: ReadSkillTreeOptions): Promise<SkillTree>;