pi-session-mcp 0.7.0 → 0.8.0

package/dist/sdk-pi-adapter.d.ts

@@ -1,4 +1,4 @@
-import { type AgentSessionEvent, type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, DefaultResourceLoader, ModelRuntime, type PromptOptions, SettingsManager } from "@earendil-works/pi-coding-agent";
+import { type AgentSessionEvent, type CreateAgentSessionOptions, type CreateAgentSessionResult, createAgentSessionFromServices, createAgentSessionRuntime, createAgentSessionServices, DefaultResourceLoader, ModelRuntime, type PromptOptions, type Skill, SettingsManager } from "@earendil-works/pi-coding-agent";
 import { type ExtensionSpec } from "./extension-spec.js";
 import type { ResolvedExecutionProfile, ThinkingLevel } from "./execution-profile.js";
 import { type McpConnectionFactory } from "./mcp-session-tools.js";
@@ -11,7 +11,7 @@ export declare const SESSION_CREATION_TIMEOUT_MS = 10000;
 export interface SdkPiAdapterDiagnostic {
     readonly level: "error";
     readonly event: "pi_session_creation_failed";
-    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind";
+    readonly stage: "runtime" | "provider" | "model" | "check_auth" | "get_auth" | "availability" | "resource_loader" | "mcp_tools" | "create_session" | "postcheck" | "extension_resolve" | "extension_load" | "extension_bind" | "skill_load";
     readonly code: PiSessionCreationErrorCode;
     readonly executionProfile: string;
     readonly provider: string;
@@ -22,6 +22,8 @@ export interface SdkPiAdapterDiagnostic {
     readonly discoveredToolCount?: number;
     /** `<name>@<version>` of the extension that failed to resolve; never a path. */
     readonly extension?: string;
+    /** The failing configured catalog alias, never a skill-file name or path. */
+    readonly skill?: string;
 }
 /** The Pi SDK session-lifecycle API used for profiles with extensions; injectable for tests. */
 export interface ExtensionSdk {
@@ -64,7 +66,7 @@ export type PromptDisposition = Parameters<NonNullable<PromptOptions["preflightR
  * typecheck (and therefore the Pi SDK canary) instead of being mapped silently.
  */
 export declare function admitsTurn(disposition: PromptDisposition): boolean;
-export declare function createPhase0ResourceLoader(cwd: string): Promise<{
+export declare function createPhase0ResourceLoader(cwd: string, skills?: readonly Skill[]): Promise<{
     resourceLoader: DefaultResourceLoader;
     settingsManager: SettingsManager;
 }>;
@@ -83,6 +85,8 @@ export declare class SdkPiSessionAdapter implements PiSessionAdapter {
         signal?: AbortSignal;
     }): Promise<PiSessionHandle>;
     private createWithExtensions;
+    private loadSkills;
+    private checkResources;
     /** Provider, model, authentication and availability, exactly as configured. */
     private resolveVerifiedModel;
     private connectMcpTools;

package/dist/sdk-pi-adapter.js

@@ -4,6 +4,7 @@ import { classifyMcpStartupError, connectSessionMcpTools, } from "./mcp-session-
 import { createStdioMcpConnection } from "./mcp-stdio-client.js";
 import { PiSessionCreationError, } from "./pi-adapter.js";
 import { resolvePiExtension } from "./pi-extensions.js";
+import { loadSelectedSkills, PiSkillError } from "./pi-skills.js";
 import { composeSessionTools, PROFILE_TOOLS } from "./session-tools.js";
 export { PROFILE_TOOLS } from "./session-tools.js";
 export const AUTH_OPERATION_TIMEOUT_MS = 5_000;
@@ -223,6 +224,9 @@ class SdkHandle {
             promptResult = this.session.prompt(text, {
                 // Client text is content, never a command: no extension command, skill or template dispatch.
                 expandPromptTemplates: false,
+                // Pi's own RPC mode uses `rpc` for input from a program over stdio, which matches an MCP
+                // client. `interactive`, the SDK default, means a human at the terminal or the CLI's print mode.
+                source: "rpc",
                 preflightResult: (disposition) => signalPreflight(admitsTurn(disposition)),
             });
         }
@@ -266,8 +270,10 @@ function isTextBlock(block) {
     const candidate = block;
     return candidate.type === "text" && typeof candidate.text === "string";
 }
-/** Resource-loader options for every embedded session: no discovery, skills, templates or themes. */
-function phase0ResourceLoaderOptions() {
+/** Independently validated skills replace package and extension discovery on every reload. */
+function phase0ResourceLoaderOptions(skills) {
+    // Keep the closure's snapshot private: the SDK may annotate or mutate returned objects.
+    const selected = skills.map((skill) => ({ ...skill, sourceInfo: { ...skill.sourceInfo } }));
     return {
         noExtensions: true,
         noSkills: true,
@@ -278,11 +284,14 @@ function phase0ResourceLoaderOptions() {
         appendSystemPrompt: [],
         systemPromptOverride: () => undefined,
         appendSystemPromptOverride: () => [],
+        skillsOverride: () => ({ skills: selected.map((skill) => ({ ...skill, sourceInfo: { ...skill.sourceInfo } })), diagnostics: [] }),
+        promptsOverride: () => ({ prompts: [], diagnostics: [] }),
+        themesOverride: () => ({ themes: [], diagnostics: [] }),
     };
 }
-export async function createPhase0ResourceLoader(cwd) {
+export async function createPhase0ResourceLoader(cwd, skills = []) {
     const settingsManager = SettingsManager.inMemory(undefined, { projectTrusted: false });
-    const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: cwd, settingsManager, ...phase0ResourceLoaderOptions() });
+    const resourceLoader = new DefaultResourceLoader({ cwd, agentDir: cwd, settingsManager, ...phase0ResourceLoaderOptions(skills) });
     await resourceLoader.reload();
     return { resourceLoader, settingsManager };
 }
@@ -307,6 +316,7 @@ export class SdkPiSessionAdapter {
         if (extensions.length > 0)
             return this.createWithExtensions(input, extensions);
         const { executionProfile } = input;
+        const skills = await this.loadSkills(input);
         let runtime;
         try {
             runtime = await this.getRuntime();
@@ -318,7 +328,7 @@ export class SdkPiSessionAdapter {
         let resourceLoader;
         let settingsManager;
         try {
-            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd));
+            ({ resourceLoader, settingsManager } = await createPhase0ResourceLoader(input.cwd, skills));
         }
         catch {
             throw this.failure(executionProfile, "resource_loader", "pi_session_creation_failed");
@@ -344,10 +354,11 @@ export class SdkPiSessionAdapter {
             await mcpTools.close();
             throw this.failure(executionProfile, "create_session", "pi_session_creation_failed");
         }
-        return this.admit(session, executionProfile, tools, mcpTools, () => disposeSdkSession(session), mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : undefined);
+        return this.admit(session, executionProfile, tools, mcpTools, () => disposeSdkSession(session), mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : undefined, "exact", skills);
     }
     async createWithExtensions(input, extensions) {
         const { cwd, executionProfile } = input;
+        const skills = await this.loadSkills(input);
         const directories = [];
         for (const extension of extensions) {
             try {
@@ -374,15 +385,18 @@ export class SdkPiSessionAdapter {
                 agentDir: cwd,
                 modelRuntime: runtime,
                 settingsManager: SettingsManager.inMemory(undefined, { projectTrusted: false }),
-                resourceLoaderOptions: { ...phase0ResourceLoaderOptions(), additionalExtensionPaths: directories },
+                resourceLoaderOptions: { ...phase0ResourceLoaderOptions(skills), additionalExtensionPaths: directories },
             }));
+            this.checkResources(services.resourceLoader, skills, executionProfile, "extension_load");
             const loaded = services.resourceLoader.getExtensions();
             if (loaded.errors.length > 0 || services.diagnostics.some((diagnostic) => diagnostic.type === "error")) {
                 throw new Error("extension load reported errors");
             }
             extensionTools = registeredExtensionTools(services);
         }
-        catch {
+        catch (error) {
+            if (error instanceof PiSessionCreationError)
+                throw error;
             throw this.failure(executionProfile, "extension_load", "extension_load_failed");
         }
         const model = await this.resolveVerifiedModel(services.modelRuntime, executionProfile);
@@ -431,6 +445,7 @@ export class SdkPiSessionAdapter {
             bound = true;
             if (bindErrors > 0)
                 throw new Error("extension hook reported errors while binding");
+            this.checkResources(sessionRuntime.session.resourceLoader, skills, executionProfile, "extension_bind");
             // A `session_start` handler may register a tool that replaces a built-in or granted tool.
             // Tools an extension registers later, during a turn, are not re-checked: allowlisted
             // extensions are trusted code.
@@ -438,15 +453,44 @@ export class SdkPiSessionAdapter {
             if (!recheck || recheck.length !== tools.length || recheck.some((name, index) => name !== tools[index]))
                 conflict = true;
         }
-        catch {
+        catch (error) {
             await cleanUp();
+            if (error instanceof PiSessionCreationError)
+                throw error;
             throw this.failure(executionProfile, "extension_bind", "extension_load_failed");
         }
         if (conflict) {
             await cleanUp();
             throw this.failure(executionProfile, "extension_bind", "extension_tool_conflict");
         }
-        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset");
+        return this.admit(sessionRuntime.session, executionProfile, tools, mcpTools, disposeRuntime, mcpTools.tools.length > 0 ? "external_mcp_activation_mismatch" : "execution_selection_mismatch", "subset", skills);
+    }
+    async loadSkills(input) {
+        try {
+            return await loadSelectedSkills(input.executionProfile.skills ?? [], input.cwd);
+        }
+        catch (error) {
+            throw this.failure(input.executionProfile, "skill_load", "skill_load_failed", error instanceof PiSkillError && error.alias !== undefined ? { skill: error.alias } : undefined);
+        }
+    }
+    checkResources(loader, skills, executionProfile, stage) {
+        let actual;
+        try {
+            actual = loader.getSkills().skills;
+        }
+        catch {
+            throw this.failure(executionProfile, stage, "skill_load_failed");
+        }
+        // Compare a multiset so duplicate entries cannot satisfy a selected file twice.
+        const identity = (skill) => JSON.stringify([skill.filePath, skill.name]);
+        const expected = skills.map(identity).sort();
+        const received = actual.map(identity).sort();
+        if (expected.length !== received.length || expected.some((entry, index) => entry !== received[index])) {
+            throw this.failure(executionProfile, stage, "skill_load_failed");
+        }
+        if (loader.getPrompts().prompts.length > 0 || loader.getThemes().themes.length > 0) {
+            throw this.failure(executionProfile, stage, "pi_session_creation_failed");
+        }
     }
     /** Provider, model, authentication and availability, exactly as configured. */
     async resolveVerifiedModel(runtime, executionProfile) {
@@ -510,8 +554,9 @@ export class SdkPiSessionAdapter {
     /** Post-verifies a created session and wraps it; a mismatch disposes it before reporting. */
     async admit(session, executionProfile, tools, mcpTools, disposeSession, toolMismatch, 
     // `subset` lets an extension narrow its own active tools; nothing outside the allowlist may be active.
-    toolCheck = "exact") {
+    toolCheck = "exact", skills = []) {
         try {
+            this.checkResources(session.resourceLoader, skills, executionProfile, "postcheck");
             if (session.model?.provider !== executionProfile.provider || session.model.id !== executionProfile.model) {
                 throw this.failure(executionProfile, "postcheck", "execution_selection_mismatch");
             }
@@ -567,6 +612,7 @@ export class SdkPiSessionAdapter {
                 ...(metadata?.toolAlias === undefined ? {} : { toolAlias: metadata.toolAlias }),
                 ...(metadata?.discoveredToolCount === undefined ? {} : { discoveredToolCount: metadata.discoveredToolCount }),
                 ...(metadata?.extension === undefined ? {} : { extension: metadata.extension }),
+                ...(metadata?.skill === undefined ? {} : { skill: metadata.skill }),
             });
         }
         catch {

package/dist/server.js

@@ -42,6 +42,7 @@ const capabilitiesSchema = z.object({
         model: z.string(),
         thinkingLevel: thinkingLevelSchema,
         extensions: z.array(z.string()),
+        skills: z.array(aliasSchema),
     }).strict()),
 }).strict();
 function result(value, isError = false) {

package/dist/session-tools.d.ts

@@ -4,6 +4,6 @@ export declare const PROFILE_TOOLS: Readonly<Record<PermissionProfile, readonly
  * The tool allowlist of a session, or undefined when an extension tool name conflicts.
  * Extension tools are active only in coding profiles, but a conflict fails closed in both,
  * so an extension can never shadow a built-in or granted tool. A name outside the safe
- * character set also fails closed.
+ * character set, or one the SDK treats as an MCP tool, also fails closed.
  */
 export declare function composeSessionTools(permissionProfile: PermissionProfile, mcpToolNames: readonly string[], extensionToolNames: readonly (readonly string[])[]): string[] | undefined;

package/dist/session-tools.js

@@ -2,20 +2,36 @@ export const PROFILE_TOOLS = {
     "read-only": ["read", "grep", "find", "ls"],
     coding: ["read", "bash", "edit", "write", "grep", "find", "ls"],
 };
-/** The SDK reads `*` in an allowlist as a glob and a leading `+` or `-` as a modifier, so those names are rejected: the first character may not be `-`. */
-const EXTENSION_TOOL_NAME = /^[A-Za-z0-9_.:][A-Za-z0-9_.:-]*$/;
+/**
+ * Letters, digits, `_` and `-`, at most 64 characters, which fits the common provider
+ * function-name limit `^[a-zA-Z0-9_-]{1,64}$`. The SDK reads `*` in an allowlist as a glob
+ * and a leading `+` or `-` as a modifier, so the first character may not be `-`.
+ */
+const EXTENSION_TOOL_NAME = /^[A-Za-z0-9_][A-Za-z0-9_-]{0,63}$/;
+/**
+ * These mirror `isMcpToolName` of Pi SDK 1.1.0 (core/mcp-servers.js), which is not a root
+ * export. When the allowlist names no `mcp__` entry, the SDK's `_isAllowedTool` keeps such
+ * tools outside the allowlist for codemode and tool_search, so an extension tool with one
+ * of these names could be active without being granted. This server's own MCP bridge
+ * tools are named `mcp_<server>_<tool>` with a single underscore, so they never collide.
+ */
+const MCP_RESERVED_PREFIX = "mcp__";
+const MCP_RESERVED_NAMES = new Set(["list_mcp_resources", "list_mcp_resource_templates", "read_mcp_resource"]);
+function isAcceptableExtensionToolName(name) {
+    return EXTENSION_TOOL_NAME.test(name) && !name.startsWith(MCP_RESERVED_PREFIX) && !MCP_RESERVED_NAMES.has(name);
+}
 /**
  * The tool allowlist of a session, or undefined when an extension tool name conflicts.
  * Extension tools are active only in coding profiles, but a conflict fails closed in both,
  * so an extension can never shadow a built-in or granted tool. A name outside the safe
- * character set also fails closed.
+ * character set, or one the SDK treats as an MCP tool, also fails closed.
  */
 export function composeSessionTools(permissionProfile, mcpToolNames, extensionToolNames) {
     const reserved = new Set([...PROFILE_TOOLS.coding, ...PROFILE_TOOLS["read-only"], ...mcpToolNames]);
     const extensionTools = [];
     for (const names of extensionToolNames) {
         for (const name of names) {
-            if (!EXTENSION_TOOL_NAME.test(name) || reserved.has(name))
+            if (!isAcceptableExtensionToolName(name) || reserved.has(name))
                 return undefined;
             reserved.add(name);
             extensionTools.push(name);

package/dist/setup-cli.d.ts

@@ -3,6 +3,8 @@ import type { SetupResult } from "./setup-result.js";
 /** Small argv adapter; command execution remains injected in SetupClientAdapter. */
 export interface SetupCliRequest extends SetupRequest {
     readonly json: boolean;
+    /** `--customize-skill <name>`: copies a shipped skill into the override directory instead of touching clients. */
+    readonly customizeSkill?: string;
 }
 export declare function parseSetupArgs(argv: readonly string[]): SetupCliRequest;
 export declare function runSetupCli(argv: readonly string[], orchestrator: SetupOrchestrator): Promise<SetupResult>;

package/dist/setup-cli.js

@@ -2,6 +2,7 @@ export function parseSetupArgs(argv) {
     let operation;
     let json = false;
     const targets = [];
+    let customizeSkill;
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
         if (argument === "--json") {
@@ -24,8 +25,23 @@ export function parseSetupArgs(argv) {
             targets.push({ client: parts[0], scope: parts[1], alias: parts[2] });
             continue;
         }
+        if (argument === "--customize-skill") {
+            if (customizeSkill !== undefined)
+                throw new Error("customize_skill_repeated");
+            const value = argv[++index];
+            if (value === undefined || value === "" || value.startsWith("-"))
+                throw new Error("customize_skill_invalid");
+            customizeSkill = value;
+            continue;
+        }
         throw new Error("argument_unsupported");
     }
+    if (customizeSkill !== undefined) {
+        // Skill customization is a dry-run or an explicit apply; it never targets a client.
+        if (targets.length > 0 || (operation !== undefined && operation !== "dry-run" && operation !== "apply"))
+            throw new Error("customize_skill_combination");
+        return operation ? { operation, targets, json, customizeSkill } : { targets, json, customizeSkill };
+    }
     return operation ? { operation, targets, json } : { targets, json };
 }
 export async function runSetupCli(argv, orchestrator) {

package/dist/setup-main.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createProductionSetup } from "./setup.js";
-/** Executable entry point: `node dist/setup-main.js [operation] --target client:scope:alias`. */
+/** Executable entry point: `node dist/setup-main.js [operation] --target client:scope:alias` or `[--apply] --customize-skill <name>`. */
 export interface SetupMainDependencies {
     readonly createSetup?: typeof createProductionSetup;
     readonly packageRoot?: string;

package/dist/setup-main.js

@@ -5,6 +5,8 @@ import { isEntryPoint } from "./entry-point.js";
 import { createProcessRunner } from "./setup-process.js";
 import { currentSetupPlatform } from "./setup-platform.js";
 import { createProductionSetup, isSupportedTarget } from "./setup.js";
+import { customizeSkill } from "./skill-customize.js";
+import { SKILL_NAME_PATTERN } from "./skill-library.js";
 import { formatSetupHuman, formatSetupResult, parseSetupArgs } from "./setup-cli.js";
 import { result } from "./setup-result.js";
 export async function main(argv = process.argv.slice(2), dependencies = {}) {
@@ -18,11 +20,21 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
         return write(cliFailure("dry-run", [], "usage_invalid", 64), json);
     }
     const operation = request.operation ?? "dry-run";
+    const failureTargets = request.customizeSkill === undefined ? request.targets : [skillTarget(request.customizeSkill)];
     if (!currentSetupPlatform())
-        return write(cliFailure(operation, request.targets, "platform_unsupported", 1), request.json);
+        return write(cliFailure(operation, failureTargets, "platform_unsupported", 1), request.json);
     const config = process.env.PI_SESSION_MCP_CONFIG;
     if (!config)
-        return write(cliFailure(operation, request.targets, "config_required", 1), request.json);
+        return write(cliFailure(operation, failureTargets, "config_required", 1), request.json);
+    if (request.customizeSkill !== undefined) {
+        const name = request.customizeSkill;
+        try {
+            return write(await customizeSkill({ name, configPath: resolve(config), apply: operation === "apply", ...(dependencies.packageRoot === undefined ? {} : { packageRoot: dependencies.packageRoot }) }), request.json);
+        }
+        catch {
+            return write(cliFailure(operation, [skillTarget(name)], "skill_customize_failed", 1), request.json);
+        }
+    }
     const root = dependencies.packageRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), "..");
     const controller = new AbortController();
     let interrupted;
@@ -51,8 +63,11 @@ export async function main(argv = process.argv.slice(2), dependencies = {}) {
         process.removeListener("SIGTERM", onTerminate);
     }
 }
+/** The skill name is echoed only when it is a valid name; arbitrary input never reaches a report. */
+function skillTarget(name) { return { client: "skills", scope: "override", alias: SKILL_NAME_PATTERN.test(name) ? name : "invalid" }; }
+function isReportableTarget(target) { return isSupportedTarget(target) || (target.client === "skills" && target.scope === "override" && (target.alias === "invalid" || SKILL_NAME_PATTERN.test(target.alias))); }
 function cliFailure(operation, targets, code, exitCode) {
-    const safeTargets = targets.filter(isSupportedTarget);
+    const safeTargets = targets.filter(isReportableTarget);
     const reported = safeTargets.length === targets.length && safeTargets.length > 0 ? safeTargets : [{ client: "invalid", scope: "invalid", alias: "invalid" }];
     return result(operation, reported.map((target) => ({ target, status: "failed", code })), "failed", exitCode);
 }

package/dist/setup-ownership.d.ts

@@ -6,6 +6,11 @@ export interface OwnershipRecord {
     readonly previous: "absent" | "equivalent";
     readonly phase: "pending" | "owned";
     readonly transactionId: string;
+    /**
+     * Skill records only, while pending: the fingerprint of setup's own copy that the pending
+     * update replaces, so an interrupted update can still be completed or removed.
+     */
+    readonly replaces?: string;
 }
 export interface RegistrationSnapshot {
     /** Opaque adapter-owned snapshot; implementations must not persist secrets. */
@@ -51,3 +56,4 @@ export declare class DurableOwnershipStore implements OwnershipStore {
     private withLock;
     private write;
 }
+export declare function isRecord(value: unknown): value is OwnershipRecord;

package/dist/setup-ownership.js

@@ -4,6 +4,7 @@ import { randomUUID } from "node:crypto";
 import { dirname } from "node:path";
 import { acquireSetupGuardian } from "./setup-process.js";
 import { assertSupportedFilesystem, currentSetupPlatform, openLockedDarwin } from "./setup-platform.js";
+import { SKILL_NAME_PATTERN } from "./skill-library.js";
 /** Safe default for one process; callers needing recovery inject a durable store. */
 export class MemoryOwnershipStore {
     entries = new Map();
@@ -209,10 +210,33 @@ async function syncDirectory(path) {
         await handle.close();
     }
 }
-function isRecord(value) { if (!value || typeof value !== "object")
-    return false; const x = value; if (!exactKeys(x, ["target", "fingerprint", "previous", "phase", "transactionId"]))
-    return false; const t = x.target; if (!t || typeof t !== "object")
-    return false; const target = t; if (!exactKeys(target, ["client", "scope", "alias"]))
-    return false; const client = target.client; const scope = target.scope; return (client === "codex" || client === "claude-code") && typeof scope === "string" && (client === "codex" ? scope === "user" : ["user", "project", "local"].includes(scope)) && target.alias === "pi-session-mcp" && typeof x.fingerprint === "string" && /^[a-f0-9]{64}$/.test(x.fingerprint) && (x.phase === "pending" || x.phase === "owned") && x.previous === "absent" && typeof x.transactionId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(x.transactionId); }
+/** `skill:<name>` for a home slot; `skill:<name>@<16 hex>` for a project slot bound to an opaque project identity. */
+const SKILL_RECORD_ALIAS = /^skill:([^@]+)(?:@([0-9a-f]{16}))?$/;
+export function isRecord(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const x = value;
+    const keys = ["target", "fingerprint", "previous", "phase", "transactionId"];
+    if (!exactKeys(x, keys) && !exactKeys(x, [...keys, "replaces"]))
+        return false;
+    if (!x.target || typeof x.target !== "object")
+        return false;
+    const target = x.target;
+    if (!exactKeys(target, ["client", "scope", "alias"]))
+        return false;
+    const { client, scope, alias } = target;
+    const registration = alias === "pi-session-mcp" &&
+        (client === "codex" ? scope === "user" : client === "claude-code" && typeof scope === "string" && ["user", "project", "local"].includes(scope));
+    const skillAlias = typeof alias === "string" ? SKILL_RECORD_ALIAS.exec(alias) : null;
+    const skill = skillAlias !== null && SKILL_NAME_PATTERN.test(skillAlias[1]) &&
+        (client === "codex" ? scope === "user" && skillAlias[2] === undefined
+            : client === "claude-code" && ((scope === "user" && skillAlias[2] === undefined) || (scope === "project" && skillAlias[2] !== undefined)));
+    // `replaces` belongs only to a pending skill record.
+    if ("replaces" in x && !(skill && x.phase === "pending" && typeof x.replaces === "string" && /^[a-f0-9]{64}$/.test(x.replaces)))
+        return false;
+    return (registration || skill) && typeof x.fingerprint === "string" && /^[a-f0-9]{64}$/.test(x.fingerprint) &&
+        (x.phase === "pending" || x.phase === "owned") && x.previous === "absent" &&
+        typeof x.transactionId === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(x.transactionId);
+}
 function exactKeys(value, expected) { const keys = Object.keys(value).sort(); return keys.length === expected.length && [...expected].sort().every((key, index) => keys[index] === key); }
 const key = (target) => `${target.client}\u0000${target.scope}\u0000${target.alias}`;

package/dist/setup-skills.d.ts

@@ -0,0 +1,37 @@
+import type { OwnershipAccess } from "./setup-ownership.js";
+import type { SetupFinding, SetupOperation, SetupTarget } from "./setup-result.js";
+export interface SetupSkillInstaller {
+    /** Called under the registration's ownership transaction for every mutation. */
+    run(operation: SetupOperation, target: SetupTarget, ownership: OwnershipAccess): Promise<readonly SetupFinding[]>;
+    /**
+     * Whether setup still owns an installed skill of exactly this registration target, so that a
+     * remove may finish the skill cleanup after the registration is already gone.
+     */
+    owns(target: SetupTarget, ownership: OwnershipAccess): Promise<boolean>;
+}
+export interface SetupSkillRoots {
+    readonly packageRoot: string;
+    readonly configPath: string;
+    readonly home: string;
+    readonly cwd: string;
+}
+/** Paths remain internal. Ownership identifies a client slot, never its location. */
+export declare class FileSetupSkillInstaller implements SetupSkillInstaller {
+    private readonly roots;
+    constructor(roots: SetupSkillRoots);
+    run(operation: SetupOperation, target: SetupTarget, ownership: OwnershipAccess): Promise<readonly SetupFinding[]>;
+    owns(target: SetupTarget, ownership: OwnershipAccess): Promise<boolean>;
+    /**
+     * The slot path and its ownership key. A project may be untrusted: only its root is
+     * canonicalized, and a link below it (for example `.claude` pointing elsewhere) makes the
+     * slot divergent, so setup never writes outside the project. In the operator's home the
+     * client's skills directory may be the operator's own link, for example into a dotfiles
+     * checkout, so it is followed. The skill entry itself is never followed in either place.
+     * A project slot's ownership is bound to an opaque, path-free identity of the project, so a
+     * remove in another project never touches this project's copy.
+     */
+    private location;
+    private library;
+    private skill;
+    private replace;
+}