pi-session-mcp 0.7.1 → 0.8.0

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;
@@ -269,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,
@@ -281,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 };
 }
@@ -310,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();
@@ -321,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");
@@ -347,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 {
@@ -377,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);
@@ -434,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.
@@ -441,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) {
@@ -513,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");
             }
@@ -570,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/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;
+}