aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix runtime skill injection across adapters

Browse Source
This commit is contained in:
Dotta
2026-03-15 07:05:01 -05:00
parent 82f253c310
commit 7675fd0856
27 changed files with 506 additions and 222 deletions
Download Patch File Download Diff File Expand all files Collapse all files

49
packages/adapter-utils/src/server-utils.ts
View File

@@ -40,6 +40,8 @@ const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
export interface PaperclipSkillEntry {
name: string;
source: string;
required?: boolean;
requiredReason?: string | null;
}
function normalizePathSlashes(value: string): string {
@@ -306,12 +308,45 @@ export async function listPaperclipSkillEntries(
.map((entry) => ({
name: entry.name,
source: path.join(root, entry.name),
required: true,
requiredReason: "Bundled Paperclip skills are always available for local adapters.",
}));
} catch {
return [];
}
}
function normalizeConfiguredPaperclipRuntimeSkills(value: unknown): PaperclipSkillEntry[] {
if (!Array.isArray(value)) return [];
const out: PaperclipSkillEntry[] = [];
for (const rawEntry of value) {
const entry = parseObject(rawEntry);
const name = asString(entry.name, "").trim();
const source = asString(entry.source, "").trim();
if (!name || !source) continue;
out.push({
name,
source,
required: asBoolean(entry.required, false),
requiredReason:
typeof entry.requiredReason === "string" && entry.requiredReason.trim().length > 0
? entry.requiredReason.trim()
: null,
});
}
return out;
}
export async function readPaperclipRuntimeSkillEntries(
config: Record<string, unknown>,
moduleDir: string,
additionalCandidates: string[] = [],
): Promise<PaperclipSkillEntry[]> {
const configuredEntries = normalizeConfiguredPaperclipRuntimeSkills(config.paperclipRuntimeSkills);
if (configuredEntries.length > 0) return configuredEntries;
return listPaperclipSkillEntries(moduleDir, additionalCandidates);
}
export async function readPaperclipSkillMarkdown(
moduleDir: string,
skillName: string,
@@ -352,6 +387,20 @@ export function readPaperclipSkillSyncPreference(config: Record<string, unknown>
};
}
export function resolvePaperclipDesiredSkillNames(
config: Record<string, unknown>,
availableEntries: Array<{ name: string; required?: boolean }>,
): string[] {
const preference = readPaperclipSkillSyncPreference(config);
const requiredSkills = availableEntries
.filter((entry) => entry.required)
.map((entry) => entry.name);
if (!preference.explicit) {
return Array.from(new Set(requiredSkills));
}
return Array.from(new Set([...requiredSkills, ...preference.desiredSkills]));
}
export function writePaperclipSkillSyncPreference(
config: Record<string, unknown>,
desiredSkills: string[],

2
packages/adapter-utils/src/types.ts
View File

@@ -152,6 +152,8 @@ export interface AdapterSkillEntry {
name: string;
desired: boolean;
managed: boolean;
required?: boolean;
requiredReason?: string | null;
state: AdapterSkillState;
sourcePath?: string | null;
targetPath?: string | null;

6
packages/adapters/claude-local/src/server/execute.ts
View File

@@ -12,7 +12,7 @@ import {
parseObject,
parseJson,
buildPaperclipEnv,
listPaperclipSkillEntries,
readPaperclipRuntimeSkillEntries,
joinPromptSections,
redactEnvForLogs,
ensureAbsoluteDirectory,
@@ -41,11 +41,11 @@ async function buildSkillsDir(config: Record<string, unknown>): Promise<string>
const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-skills-"));
const target = path.join(tmp, ".claude", "skills");
await fs.mkdir(target, { recursive: true });
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const desiredNames = new Set(
resolveClaudeDesiredSkillNames(
config,
availableEntries.map((entry) => entry.name),
availableEntries,
),
);
for (const entry of availableEntries) {

22
packages/adapters/claude-local/src/server/skills.ts
View File

@@ -6,24 +6,16 @@ import type {
AdapterSkillSnapshot,
} from "@paperclipai/adapter-utils";
import {
listPaperclipSkillEntries,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
function resolveDesiredSkillNames(config: Record<string, unknown>, availableSkillNames: string[]) {
const preference = readPaperclipSkillSyncPreference(config);
return preference.explicit ? preference.desiredSkills : availableSkillNames;
}
async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const desiredSkills = resolveDesiredSkillNames(
config,
availableEntries.map((entry) => entry.name),
);
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
name: entry.name,
@@ -35,6 +27,8 @@ async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promis
detail: desiredSet.has(entry.name)
? "Will be mounted into the ephemeral Claude skill directory on the next run."
: null,
required: Boolean(entry.required),
requiredReason: entry.requiredReason ?? null,
}));
const warnings: string[] = [];
@@ -77,7 +71,7 @@ export async function syncClaudeSkills(
export function resolveClaudeDesiredSkillNames(
config: Record<string, unknown>,
availableSkillNames: string[],
availableEntries: Array<{ name: string; required?: boolean }>,
) {
return resolveDesiredSkillNames(config, availableSkillNames);
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

18
packages/adapters/codex-local/src/server/execute.ts
View File

@@ -14,7 +14,8 @@ import {
ensureCommandResolvable,
ensurePaperclipSkillSymlink,
ensurePathInEnv,
listPaperclipSkillEntries,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
removeMaintainerOnlySkillSymlinks,
renderTemplate,
joinPromptSections,
@@ -92,7 +93,7 @@ async function isLikelyPaperclipRuntimeSkillSource(candidate: string, skillName:
type EnsureCodexSkillsInjectedOptions = {
skillsHome?: string;
skillsEntries?: Awaited<ReturnType<typeof listPaperclipSkillEntries>>;
skillsEntries?: Array<{ name: string; source: string }>;
desiredSkillNames?: string[];
linkSkill?: (source: string, target: string) => Promise<void>;
};
@@ -101,7 +102,7 @@ export async function ensureCodexSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
options: EnsureCodexSkillsInjectedOptions = {},
) {
const allSkillsEntries = options.skillsEntries ?? await listPaperclipSkillEntries(__moduleDir);
const allSkillsEntries = options.skillsEntries ?? await readPaperclipRuntimeSkillEntries({}, __moduleDir);
const desiredSkillNames =
options.desiredSkillNames ?? allSkillsEntries.map((entry) => entry.name);
const desiredSet = new Set(desiredSkillNames);
@@ -220,10 +221,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
typeof envConfig.CODEX_HOME === "string" && envConfig.CODEX_HOME.trim().length > 0
? path.resolve(envConfig.CODEX_HOME.trim())
: null;
const desiredSkillNames = resolveCodexDesiredSkillNames(
config,
(await listPaperclipSkillEntries(__moduleDir)).map((entry) => entry.name),
);
const codexSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const desiredSkillNames = resolveCodexDesiredSkillNames(config, codexSkillEntries);
await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
const preparedWorktreeCodexHome =
configuredCodexHome ? null : await prepareWorktreeCodexHome(process.env, onLog);
@@ -231,11 +230,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
await ensureCodexSkillsInjected(
onLog,
effectiveCodexHome
? {
? {
skillsHome: path.join(effectiveCodexHome, "skills"),
skillsEntries: codexSkillEntries,
desiredSkillNames,
}
: { desiredSkillNames },
: { skillsEntries: codexSkillEntries, desiredSkillNames },
);
const hasExplicitApiKey =
typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;

29
packages/adapters/codex-local/src/server/skills.ts
View File

@@ -8,8 +8,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
listPaperclipSkillEntries,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
import { resolveCodexHomeDir } from "./codex-home.js";
@@ -29,11 +29,6 @@ function resolveCodexSkillsHome(config: Record<string, unknown>) {
return path.join(home, "skills");
}
function resolveDesiredSkillNames(config: Record<string, unknown>, availableSkillNames: string[]) {
const preference = readPaperclipSkillSyncPreference(config);
return preference.explicit ? preference.desiredSkills : availableSkillNames;
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const desiredSkills = resolveDesiredSkillNames(
config,
availableEntries.map((entry) => entry.name),
);
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveCodexSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -97,6 +89,8 @@ async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
@@ -147,8 +141,11 @@ export async function syncCodexSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const desiredSet = new Set(desiredSkills);
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
]);
const skillsHome = resolveCodexSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -173,7 +170,7 @@ export async function syncCodexSkills(
export function resolveCodexDesiredSkillNames(
config: Record<string, unknown>,
availableSkillNames: string[],
availableEntries: Array<{ name: string; required?: boolean }>,
) {
return resolveDesiredSkillNames(config, availableSkillNames);
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

13
packages/adapters/cursor-local/src/server/execute.ts
View File

@@ -14,8 +14,8 @@ import {
ensureCommandResolvable,
ensurePaperclipSkillSymlink,
ensurePathInEnv,
listPaperclipSkillEntries,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
removeMaintainerOnlySkillSymlinks,
renderTemplate,
joinPromptSections,
@@ -98,7 +98,7 @@ export async function ensureCursorSkillsInjected(
? (await fs.readdir(options.skillsDir, { withFileTypes: true }))
.filter((entry) => entry.isDirectory())
.map((entry) => ({ name: entry.name, source: path.join(options.skillsDir!, entry.name) }))
: await listPaperclipSkillEntries(__moduleDir));
: await readPaperclipRuntimeSkillEntries({}, __moduleDir));
if (skillsEntries.length === 0) return;
const skillsHome = options.skillsHome ?? cursorSkillsHome();
@@ -169,11 +169,8 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
const cursorSkillEntries = await listPaperclipSkillEntries(__moduleDir);
const cursorPreference = readPaperclipSkillSyncPreference(config);
const desiredCursorSkillNames = cursorPreference.explicit
? cursorPreference.desiredSkills
: cursorSkillEntries.map((entry) => entry.name);
const cursorSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const desiredCursorSkillNames = resolvePaperclipDesiredSkillNames(config, cursorSkillEntries);
await ensureCursorSkillsInjected(onLog, {
skillsEntries: cursorSkillEntries.filter((entry) => desiredCursorSkillNames.includes(entry.name)),
});

29
packages/adapters/cursor-local/src/server/skills.ts
View File

@@ -9,8 +9,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
listPaperclipSkillEntries,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -29,11 +29,6 @@ function resolveCursorSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".cursor", "skills");
}
function resolveDesiredSkillNames(config: Record<string, unknown>, availableSkillNames: string[]) {
const preference = readPaperclipSkillSyncPreference(config);
return preference.explicit ? preference.desiredSkills : availableSkillNames;
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const desiredSkills = resolveDesiredSkillNames(
config,
availableEntries.map((entry) => entry.name),
);
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveCursorSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -97,6 +89,8 @@ async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promis
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
@@ -147,8 +141,11 @@ export async function syncCursorSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const desiredSet = new Set(desiredSkills);
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
]);
const skillsHome = resolveCursorSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -173,7 +170,7 @@ export async function syncCursorSkills(
export function resolveCursorDesiredSkillNames(
config: Record<string, unknown>,
availableSkillNames: string[],
availableEntries: Array<{ name: string; required?: boolean }>,
) {
return resolveDesiredSkillNames(config, availableSkillNames);
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

25
packages/adapters/gemini-local/src/server/execute.ts
View File

@@ -15,8 +15,8 @@ import {
ensurePaperclipSkillSymlink,
joinPromptSections,
ensurePathInEnv,
listPaperclipSkillEntries,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
removeMaintainerOnlySkillSymlinks,
parseObject,
redactEnvForLogs,
@@ -85,12 +85,12 @@ function geminiSkillsHome(): string {
*/
async function ensureGeminiSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
skillsEntries: Array<{ name: string; source: string }>,
desiredSkillNames?: string[],
): Promise<void> {
const allSkillsEntries = await listPaperclipSkillEntries(__moduleDir);
const desiredSet = new Set(desiredSkillNames ?? allSkillsEntries.map((entry) => entry.name));
const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.name));
if (skillsEntries.length === 0) return;
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.name));
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.name));
if (selectedEntries.length === 0) return;
const skillsHome = geminiSkillsHome();
try {
@@ -104,7 +104,7 @@ async function ensureGeminiSkillsInjected(
}
const removedSkills = await removeMaintainerOnlySkillSymlinks(
skillsHome,
skillsEntries.map((entry) => entry.name),
selectedEntries.map((entry) => entry.name),
);
for (const skillName of removedSkills) {
await onLog(
@@ -113,7 +113,7 @@ async function ensureGeminiSkillsInjected(
);
}
for (const entry of skillsEntries) {
for (const entry of selectedEntries) {
const target = path.join(skillsHome, entry.name);
try {
@@ -160,12 +160,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
const geminiSkillEntries = await listPaperclipSkillEntries(__moduleDir);
const geminiPreference = readPaperclipSkillSyncPreference(config);
const desiredGeminiSkillNames = geminiPreference.explicit
? geminiPreference.desiredSkills
: geminiSkillEntries.map((entry) => entry.name);
await ensureGeminiSkillsInjected(onLog, desiredGeminiSkillNames);
const geminiSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const desiredGeminiSkillNames = resolvePaperclipDesiredSkillNames(config, geminiSkillEntries);
await ensureGeminiSkillsInjected(onLog, geminiSkillEntries, desiredGeminiSkillNames);
const envConfig = parseObject(config.env);
const hasExplicitApiKey =

29
packages/adapters/gemini-local/src/server/skills.ts
View File

@@ -9,8 +9,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
listPaperclipSkillEntries,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -29,11 +29,6 @@ function resolveGeminiSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".gemini", "skills");
}
function resolveDesiredSkillNames(config: Record<string, unknown>, availableSkillNames: string[]) {
const preference = readPaperclipSkillSyncPreference(config);
return preference.explicit ? preference.desiredSkills : availableSkillNames;
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const desiredSkills = resolveDesiredSkillNames(
config,
availableEntries.map((entry) => entry.name),
);
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveGeminiSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -97,6 +89,8 @@ async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promis
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
@@ -147,8 +141,11 @@ export async function syncGeminiSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const desiredSet = new Set(desiredSkills);
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
]);
const skillsHome = resolveGeminiSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -173,7 +170,7 @@ export async function syncGeminiSkills(
export function resolveGeminiDesiredSkillNames(
config: Record<string, unknown>,
availableSkillNames: string[],
availableEntries: Array<{ name: string; required?: boolean }>,
) {
return resolveDesiredSkillNames(config, availableSkillNames);
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

53
packages/adapters/opencode-local/src/server/execute.ts
View File

@@ -13,19 +13,18 @@ import {
redactEnvForLogs,
ensureAbsoluteDirectory,
ensureCommandResolvable,
ensurePaperclipSkillSymlink,
ensurePathInEnv,
renderTemplate,
runChildProcess,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
import { isOpenCodeUnknownSessionError, parseOpenCodeJsonl } from "./parse.js";
import { ensureOpenCodeModelConfiguredAndAvailable } from "./models.js";
import { removeMaintainerOnlySkillSymlinks } from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
const PAPERCLIP_SKILLS_CANDIDATES = [
path.resolve(__moduleDir, "../../skills"),
path.resolve(__moduleDir, "../../../../../skills"),
];
function firstNonEmptyLine(text: string): string {
return (
@@ -47,38 +46,34 @@ function claudeSkillsHome(): string {
return path.join(os.homedir(), ".claude", "skills");
}
async function resolvePaperclipSkillsDir(): Promise<string | null> {
for (const candidate of PAPERCLIP_SKILLS_CANDIDATES) {
const isDir = await fs.stat(candidate).then((s) => s.isDirectory()).catch(() => false);
if (isDir) return candidate;
}
return null;
}
async function ensureOpenCodeSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
skillsEntries: Array<{ name: string; source: string }>,
desiredSkillNames?: string[],
) {
const skillsDir = await resolvePaperclipSkillsDir();
if (!skillsDir) return;
const skillsHome = claudeSkillsHome();
await fs.mkdir(skillsHome, { recursive: true });
const entries = await fs.readdir(skillsDir, { withFileTypes: true });
const desiredSet = new Set(desiredSkillNames ?? entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name));
for (const entry of entries) {
if (!entry.isDirectory()) continue;
if (!desiredSet.has(entry.name)) continue;
const source = path.join(skillsDir, entry.name);
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.name));
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.name));
const removedSkills = await removeMaintainerOnlySkillSymlinks(
skillsHome,
selectedEntries.map((entry) => entry.name),
);
for (const skillName of removedSkills) {
await onLog(
"stderr",
`[paperclip] Removed maintainer-only OpenCode skill "${skillName}" from ${skillsHome}\n`,
);
}
for (const entry of selectedEntries) {
const target = path.join(skillsHome, entry.name);
const existing = await fs.lstat(target).catch(() => null);
if (existing) continue;
try {
await fs.symlink(source, target);
const result = await ensurePaperclipSkillSymlink(entry.source, target);
if (result === "skipped") continue;
await onLog(
"stderr",
`[paperclip] Injected OpenCode skill "${entry.name}" into ${skillsHome}\n`,
`[paperclip] ${result === "repaired" ? "Repaired" : "Injected"} OpenCode skill "${entry.name}" into ${skillsHome}\n`,
);
} catch (err) {
await onLog(
@@ -117,10 +112,12 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const effectiveWorkspaceCwd = useConfiguredInsteadOfAgentHome ? "" : workspaceCwd;
const cwd = effectiveWorkspaceCwd || configuredCwd || process.cwd();
await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
const openCodePreference = readPaperclipSkillSyncPreference(config);
const openCodeSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const desiredOpenCodeSkillNames = resolvePaperclipDesiredSkillNames(config, openCodeSkillEntries);
await ensureOpenCodeSkillsInjected(
onLog,
openCodePreference.explicit ? openCodePreference.desiredSkills : undefined,
openCodeSkillEntries,
desiredOpenCodeSkillNames,
);
const envConfig = parseObject(config.env);

29
packages/adapters/opencode-local/src/server/skills.ts
View File

@@ -9,8 +9,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
listPaperclipSkillEntries,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -29,11 +29,6 @@ function resolveOpenCodeSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".claude", "skills");
}
function resolveDesiredSkillNames(config: Record<string, unknown>, availableSkillNames: string[]) {
const preference = readPaperclipSkillSyncPreference(config);
return preference.explicit ? preference.desiredSkills : availableSkillNames;
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const desiredSkills = resolveDesiredSkillNames(
config,
availableEntries.map((entry) => entry.name),
);
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolveOpenCodeSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -100,6 +92,8 @@ async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Prom
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
@@ -150,8 +144,11 @@ export async function syncOpenCodeSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const desiredSet = new Set(desiredSkills);
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
]);
const skillsHome = resolveOpenCodeSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -176,7 +173,7 @@ export async function syncOpenCodeSkills(
export function resolveOpenCodeDesiredSkillNames(
config: Record<string, unknown>,
availableSkillNames: string[],
availableEntries: Array<{ name: string; required?: boolean }>,
) {
return resolveDesiredSkillNames(config, availableSkillNames);
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

25
packages/adapters/pi-local/src/server/execute.ts
View File

@@ -15,8 +15,8 @@ import {
ensureCommandResolvable,
ensurePaperclipSkillSymlink,
ensurePathInEnv,
listPaperclipSkillEntries,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
removeMaintainerOnlySkillSymlinks,
renderTemplate,
runChildProcess,
@@ -53,18 +53,18 @@ function parseModelId(model: string | null): string | null {
async function ensurePiSkillsInjected(
onLog: AdapterExecutionContext["onLog"],
skillsEntries: Array<{ name: string; source: string }>,
desiredSkillNames?: string[],
) {
const allSkillsEntries = await listPaperclipSkillEntries(__moduleDir);
const desiredSet = new Set(desiredSkillNames ?? allSkillsEntries.map((entry) => entry.name));
const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.name));
if (skillsEntries.length === 0) return;
const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.name));
const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.name));
if (selectedEntries.length === 0) return;
const piSkillsHome = path.join(os.homedir(), ".pi", "agent", "skills");
await fs.mkdir(piSkillsHome, { recursive: true });
const removedSkills = await removeMaintainerOnlySkillSymlinks(
piSkillsHome,
skillsEntries.map((entry) => entry.name),
selectedEntries.map((entry) => entry.name),
);
for (const skillName of removedSkills) {
await onLog(
@@ -73,7 +73,7 @@ async function ensurePiSkillsInjected(
);
}
for (const entry of skillsEntries) {
for (const entry of selectedEntries) {
const target = path.join(piSkillsHome, entry.name);
try {
@@ -139,12 +139,9 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
await ensureSessionsDir();
// Inject skills
const piSkillEntries = await listPaperclipSkillEntries(__moduleDir);
const piPreference = readPaperclipSkillSyncPreference(config);
const desiredPiSkillNames = piPreference.explicit
? piPreference.desiredSkills
: piSkillEntries.map((entry) => entry.name);
await ensurePiSkillsInjected(onLog, desiredPiSkillNames);
const piSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const desiredPiSkillNames = resolvePaperclipDesiredSkillNames(config, piSkillEntries);
await ensurePiSkillsInjected(onLog, piSkillEntries, desiredPiSkillNames);
// Build environment
const envConfig = parseObject(config.env);

29
packages/adapters/pi-local/src/server/skills.ts
View File

@@ -9,8 +9,8 @@ import type {
} from "@paperclipai/adapter-utils";
import {
ensurePaperclipSkillSymlink,
listPaperclipSkillEntries,
readPaperclipSkillSyncPreference,
readPaperclipRuntimeSkillEntries,
resolvePaperclipDesiredSkillNames,
} from "@paperclipai/adapter-utils/server-utils";
const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
@@ -29,11 +29,6 @@ function resolvePiSkillsHome(config: Record<string, unknown>) {
return path.join(home, ".pi", "agent", "skills");
}
function resolveDesiredSkillNames(config: Record<string, unknown>, availableSkillNames: string[]) {
const preference = readPaperclipSkillSyncPreference(config);
return preference.explicit ? preference.desiredSkills : availableSkillNames;
}
async function readInstalledSkillTargets(skillsHome: string) {
const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
const out = new Map<string, { targetPath: string | null; kind: "symlink" | "directory" | "file" }>();
@@ -57,12 +52,9 @@ async function readInstalledSkillTargets(skillsHome: string) {
}
async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
const desiredSkills = resolveDesiredSkillNames(
config,
availableEntries.map((entry) => entry.name),
);
const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
const desiredSet = new Set(desiredSkills);
const skillsHome = resolvePiSkillsHome(config);
const installed = await readInstalledSkillTargets(skillsHome);
@@ -97,6 +89,8 @@ async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<Ad
sourcePath: available.source,
targetPath: path.join(skillsHome, available.name),
detail,
required: Boolean(available.required),
requiredReason: available.requiredReason ?? null,
});
}
@@ -147,8 +141,11 @@ export async function syncPiSkills(
ctx: AdapterSkillContext,
desiredSkills: string[],
): Promise<AdapterSkillSnapshot> {
const availableEntries = await listPaperclipSkillEntries(__moduleDir);
const desiredSet = new Set(desiredSkills);
const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
const desiredSet = new Set([
...desiredSkills,
...availableEntries.filter((entry) => entry.required).map((entry) => entry.name),
]);
const skillsHome = resolvePiSkillsHome(ctx.config);
await fs.mkdir(skillsHome, { recursive: true });
const installed = await readInstalledSkillTargets(skillsHome);
@@ -173,7 +170,7 @@ export async function syncPiSkills(
export function resolvePiDesiredSkillNames(
config: Record<string, unknown>,
availableSkillNames: string[],
availableEntries: Array<{ name: string; required?: boolean }>,
) {
return resolveDesiredSkillNames(config, availableSkillNames);
return resolvePaperclipDesiredSkillNames(config, availableEntries);
}

2
packages/shared/src/types/adapter-skills.ts
View File

@@ -12,6 +12,8 @@ export interface AgentSkillEntry {
name: string;
desired: boolean;
managed: boolean;
required?: boolean;
requiredReason?: string | null;
state: AgentSkillState;
sourcePath?: string | null;
targetPath?: string | null;

2
packages/shared/src/validators/adapter-skills.ts
View File

@@ -19,6 +19,8 @@ export const agentSkillEntrySchema = z.object({
name: z.string().min(1),
desired: z.boolean(),
managed: z.boolean(),
required: z.boolean().optional(),
requiredReason: z.string().nullable().optional(),
state: agentSkillStateSchema,
sourcePath: z.string().nullable().optional(),
targetPath: z.string().nullable().optional(),