The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
fix(adapters): restore Paperclip skill for legacy runners (#12225)
Dottaa9d0927fe837
diff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex 33c5666c70..d5bcfb0349 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -756,6 +756,15 @@ Server and CLI import the generated manifest; they do not crawl repositorypaths at request time. Root `skills/` remains reserved for Paperclip runtimeskills and is not part of the catalog.+Skill-capable legacy local adapters always select the bundled+`paperclipai/paperclip/paperclip` operational skill when it is present in the+runtime inventory. This applies to existing agents without a stored skill+preference and to explicit empty optional-skill selections. The operational+skill supplies the control-plane workflow that those adapters need for+heartbeats. Other runtime skills remain controlled by+`paperclipSkillSync.desiredSkills`. The native `paperclip_runner` does not use+this legacy default because its protocol supplies the control-plane contract.+Validate the catalog without writing the manifest:```shdiff --git a/packages/adapter-utils/src/acpx-engine/execute.test.ts b/packages/adapter-utils/src/acpx-engine/execute.test.tsindex 9ba7ea4dde..63c5fe4789 100644--- a/packages/adapter-utils/src/acpx-engine/execute.test.ts+++ b/packages/adapter-utils/src/acpx-engine/execute.test.ts@@ -1182,6 +1182,26 @@ describe("shared ACPX engine runtime behavior", () => {expect(await pathExists(path.join(codexHome, "skills", remove.runtimeName))).toBe(false);});+ it.skipIf(process.platform === "win32")("keeps the operational skill in an ACPX Codex home after an empty replacement", async () => {+ const root = await makeTempRoot();+ const skillRoot = path.join(root, "skills");+ const codexHome = path.join(root, "codex-home");+ const operational = {+ ...await createSkill(skillRoot, "paperclip"),+ key: "paperclipai/paperclip/paperclip",+ };++ await runExecutor({+ agent: "codex",+ stateDir: path.join(root, "state"),+ env: { CODEX_HOME: codexHome },+ paperclipRuntimeSkills: [operational],+ paperclipSkillSync: { desiredSkills: [] },+ });++ expect(await pathExists(path.join(codexHome, "skills", operational.runtimeName, "SKILL.md"))).toBe(true);+ });+it.skipIf(process.platform === "win32")("removes legacy ACPX Codex skill symlinks when a skill is no longer desired", async () => {const root = await makeTempRoot();const skillRoot = path.join(root, "skills");diff --git a/packages/adapter-utils/src/acpx-engine/execute.ts b/packages/adapter-utils/src/acpx-engine/execute.tsindex 4442e7f642..29261ea596 100644--- a/packages/adapter-utils/src/acpx-engine/execute.ts+++ b/packages/adapter-utils/src/acpx-engine/execute.ts@@ -64,7 +64,7 @@ import {renderTemplate,resolvePaperclipInstanceRootForAdapter,selectPaperclipTaskMarkdown,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,removeMaintainerOnlySkillSymlinks,rewriteWorkspaceCwdEnvVarsForExecution,shapePaperclipWorkspaceEnvForExecution,@@ -910,7 +910,7 @@ async function resolveSelectedRuntimeSkills(moduleDir: string,): Promise<{ allSkills: PaperclipSkillEntry[]; selectedSkills: PaperclipSkillEntry[]; desiredSkillNames: string[] }> {const allSkills = await readPaperclipRuntimeSkillEntries(config, moduleDir);- const desiredSkillNames = resolvePaperclipDesiredSkillNames(config, allSkills);+ const desiredSkillNames = resolveLegacyPaperclipDesiredSkillNames(config, allSkills);const desiredSet = new Set(desiredSkillNames);return {allSkills,@@ -1852,7 +1852,7 @@ async function buildRuntime(input: {skillsIdentity = preparedSkills.identity;skillCommandNotes.push(...preparedSkills.commandNotes);} else {- const desired = resolvePaperclipDesiredSkillNames(+ const desired = resolveLegacyPaperclipDesiredSkillNames(config,await readPaperclipRuntimeSkillEntries(config, input.engine.moduleDir),);diff --git a/packages/adapter-utils/src/server-utils.test.ts b/packages/adapter-utils/src/server-utils.test.tsindex 3b497239e8..17063ef424 100644--- a/packages/adapter-utils/src/server-utils.test.ts+++ b/packages/adapter-utils/src/server-utils.test.ts@@ -13,8 +13,11 @@ import {buildPaperclipEnv,DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,materializePaperclipSkillCopy,+ PAPERCLIP_OPERATIONAL_SKILL_KEY,refreshPaperclipWorkspaceEnvForExecution,renderPaperclipWakePrompt,+ resolveLegacyPaperclipDesiredSkillNames,+ resolvePaperclipDesiredSkillNames,selectPaperclipTaskMarkdown,runningProcesses,runChildProcess,@@ -28,6 +31,45 @@ import {WATCHDOG_DEFAULT_MANDATE,} from "./server-utils.js";+describe("legacy adapter skill selection", () => {+ const operationalEntry = {+ key: PAPERCLIP_OPERATIONAL_SKILL_KEY,+ runtimeName: "paperclip",+ };+ const optionalEntry = {+ key: "company/example/reviewer",+ runtimeName: "reviewer",+ };++ it("keeps the operational skill selected without a stored preference", () => {+ expect(resolveLegacyPaperclipDesiredSkillNames({}, [operationalEntry, optionalEntry])).toEqual([+ PAPERCLIP_OPERATIONAL_SKILL_KEY,+ ]);+ });++ it("keeps the operational skill selected after an explicit empty replacement", () => {+ expect(resolveLegacyPaperclipDesiredSkillNames(+ { paperclipSkillSync: { desiredSkills: [] } },+ [operationalEntry, optionalEntry],+ )).toEqual([PAPERCLIP_OPERATIONAL_SKILL_KEY]);+ });++ it("does not force optional skills or synthesize a missing operational entry", () => {+ const config = { paperclipSkillSync: { desiredSkills: [optionalEntry.key] } };+ expect(resolveLegacyPaperclipDesiredSkillNames(config, [operationalEntry, optionalEntry])).toEqual([+ PAPERCLIP_OPERATIONAL_SKILL_KEY,+ optionalEntry.key,+ ]);+ expect(resolveLegacyPaperclipDesiredSkillNames(config, [optionalEntry])).toEqual([+ optionalEntry.key,+ ]);+ });++ it("leaves the configurable resolver available for native runners", () => {+ expect(resolvePaperclipDesiredSkillNames({}, [operationalEntry])).toEqual([]);+ });+});+function isPidAlive(pid: number) {try {process.kill(pid, 0);diff --git a/packages/adapter-utils/src/server-utils.ts b/packages/adapter-utils/src/server-utils.tsindex 48d229fb47..d3e73b35ce 100644--- a/packages/adapter-utils/src/server-utils.ts+++ b/packages/adapter-utils/src/server-utils.ts@@ -2989,6 +2989,33 @@ export function resolvePaperclipDesiredSkillNames(return Array.from(new Set(desiredSkills));}+/**+ * Legacy adapters call the Paperclip API through the operational skill. Keep+ * that skill mounted even when an agent predates skill preferences or carries+ * an explicit empty desired set. Native runners provide the same authority+ * through their protocol and must continue to use the configurable-only+ * resolver above.+ */+export const PAPERCLIP_OPERATIONAL_SKILL_KEY = "paperclipai/paperclip/paperclip";++export function resolveLegacyPaperclipDesiredSkillNames(+ config: Record<string, unknown>,+ availableEntries: Array<{ key: string; runtimeName?: string | null }>,+): string[] {+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const operationalEntry = availableEntries.find(+ (entry) => entry.key.trim().toLowerCase() === PAPERCLIP_OPERATIONAL_SKILL_KEY,+ );+ if (!operationalEntry) return desiredSkills;++ return [+ operationalEntry.key,+ ...desiredSkills.filter(+ (key) => key.trim().toLowerCase() !== PAPERCLIP_OPERATIONAL_SKILL_KEY,+ ),+ ];+}+export function writePaperclipSkillSyncPreference(config: Record<string, unknown>,desiredSkills: Array<string | PaperclipDesiredSkillEntry>,diff --git a/packages/adapters/claude-local/src/server/skills.ts b/packages/adapters/claude-local/src/server/skills.tsindex 75fb27ce33..724263605c 100644--- a/packages/adapters/claude-local/src/server/skills.ts+++ b/packages/adapters/claude-local/src/server/skills.ts@@ -9,7 +9,7 @@ import {buildRuntimeMountedSkillSnapshot,readPaperclipRuntimeSkillEntries,readInstalledSkillTargets,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));@@ -30,7 +30,7 @@ function resolveClaudeSkillsHome(config: Record<string, unknown>) {async function buildClaudeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const desiredSkills = resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);const skillsHome = resolveClaudeSkillsHome(config);const installed = await readInstalledSkillTargets(skillsHome);return buildRuntimeMountedSkillSnapshot({@@ -60,5 +60,5 @@ export function resolveClaudeDesiredSkillNames(config: Record<string, unknown>,availableEntries: Array<{ key: string; required?: boolean }>,) {- return resolvePaperclipDesiredSkillNames(config, availableEntries);+ return resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);}diff --git a/packages/adapters/codex-local/src/server/execute.ts b/packages/adapters/codex-local/src/server/execute.tsindex f2f0635ede..430a77bcc2 100644--- a/packages/adapters/codex-local/src/server/execute.ts+++ b/packages/adapters/codex-local/src/server/execute.ts@@ -43,7 +43,6 @@ import {isPaperclipSkillSourceMissing,readPaperclipRuntimeSkillEntries,readPaperclipIssueWorkModeFromContext,- resolvePaperclipDesiredSkillNames,renderTemplate,renderPaperclipWakePrompt,isPaperclipRecoveryWakePayload,diff --git a/packages/adapters/codex-local/src/server/skills.ts b/packages/adapters/codex-local/src/server/skills.tsindex 6d52cb338b..bdf4879dc8 100644--- a/packages/adapters/codex-local/src/server/skills.ts+++ b/packages/adapters/codex-local/src/server/skills.ts@@ -7,6 +7,7 @@ import type {import {buildRuntimeMountedSkillSnapshot,readPaperclipRuntimeSkillEntries,+ resolveLegacyPaperclipDesiredSkillNames,resolvePaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";@@ -14,11 +15,14 @@ const __moduleDir = path.dirname(fileURLToPath(import.meta.url));async function buildCodexSkillSnapshot(config: Record<string, unknown>,+ adapterType: string,): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const desiredSkills = adapterType === "paperclip_runner"+ ? resolvePaperclipDesiredSkillNames(config, availableEntries)+ : resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);return buildRuntimeMountedSkillSnapshot({- adapterType: "codex_local",+ adapterType,availableEntries,desiredSkills,configuredDetail: "Will be linked into the effective CODEX_HOME/skills/ directory on the next run.",@@ -26,19 +30,19 @@ async function buildCodexSkillSnapshot(}export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {- return buildCodexSkillSnapshot(ctx.config);+ return buildCodexSkillSnapshot(ctx.config, ctx.adapterType);}export async function syncCodexSkills(ctx: AdapterSkillContext,_desiredSkills: string[],): Promise<AdapterSkillSnapshot> {- return buildCodexSkillSnapshot(ctx.config);+ return buildCodexSkillSnapshot(ctx.config, ctx.adapterType);}export function resolveCodexDesiredSkillNames(config: Record<string, unknown>,availableEntries: Array<{ key: string; required?: boolean }>,) {- return resolvePaperclipDesiredSkillNames(config, availableEntries);+ return resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);}diff --git a/packages/adapters/cursor-local/src/server/execute.ts b/packages/adapters/cursor-local/src/server/execute.tsindex 30f23950e8..2a7edeebf0 100644--- a/packages/adapters/cursor-local/src/server/execute.ts+++ b/packages/adapters/cursor-local/src/server/execute.ts@@ -39,7 +39,7 @@ import {isPaperclipSkillSourceMissing,readPaperclipRuntimeSkillEntries,readPaperclipIssueWorkModeFromContext,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,removeMaintainerOnlySkillSymlinks,renderTemplate,renderPaperclipWakePrompt,@@ -53,6 +53,7 @@ import { parseCursorJsonl, isCursorUnknownSessionError } from "./parse.js";import { prepareCursorSandboxCommand } from "./remote-command.js";import { normalizeCursorStreamLine } from "../shared/stream.js";import { hasCursorTrustBypassArg } from "../shared/trust.js";+import { resolveCursorSkillsHome } from "./skills.js";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));@@ -117,16 +118,12 @@ function renderPaperclipEnvNote(env: Record<string, string>): string {].join("\n");}-function cursorSkillsHome(): string {- return path.join(os.homedir(), ".cursor", "skills");-}-async function buildCursorSkillsDir(config: Record<string, unknown>): Promise<string> {const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-cursor-skills-"));const target = path.join(tmp, "skills");await fs.mkdir(target, { recursive: true });const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));+ const desiredNames = new Set(resolveLegacyPaperclipDesiredSkillNames(config, availableEntries));for (const entry of availableEntries) {if (!desiredNames.has(entry.key)) continue;if (isPaperclipSkillSourceMissing(entry)) continue;@@ -158,7 +155,7 @@ export async function ensureCursorSkillsInjected(: await readPaperclipRuntimeSkillEntries({}, __moduleDir));if (skillsEntries.length === 0) return;- const skillsHome = options.skillsHome ?? cursorSkillsHome();+ const skillsHome = options.skillsHome ?? resolveCursorSkillsHome({});try {await fs.mkdir(skillsHome, { recursive: true });} catch (err) {@@ -233,12 +230,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExeclet effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);await ensureAbsoluteDirectory(cwd, { createIfMissing: true });const cursorSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredCursorSkillNames = resolvePaperclipDesiredSkillNames(config, cursorSkillEntries);+ const desiredCursorSkillNames = resolveLegacyPaperclipDesiredSkillNames(config, cursorSkillEntries);if (!executionTargetIsRemote) {await ensureCursorSkillsInjected(onLog, {skillsEntries: cursorSkillEntries.filter((entry) => desiredCursorSkillNames.includes(entry.key) && !isPaperclipSkillSourceMissing(entry),),+ skillsHome: resolveCursorSkillsHome(config),});}diff --git a/packages/adapters/cursor-local/src/server/skills.ts b/packages/adapters/cursor-local/src/server/skills.tsindex 854fc133a6..a725df4378 100644--- a/packages/adapters/cursor-local/src/server/skills.ts+++ b/packages/adapters/cursor-local/src/server/skills.ts@@ -11,7 +11,7 @@ import {ensurePaperclipSkillSymlink,readPaperclipRuntimeSkillEntries,readInstalledSkillTargets,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));@@ -20,7 +20,7 @@ function asString(value: unknown): string | null {return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;}-function resolveCursorSkillsHome(config: Record<string, unknown>) {+export function resolveCursorSkillsHome(config: Record<string, unknown>) {const env =typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)? (config.env as Record<string, unknown>)@@ -32,7 +32,7 @@ function resolveCursorSkillsHome(config: Record<string, unknown>) {async function buildCursorSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const desiredSkills = resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);const skillsHome = resolveCursorSkillsHome(config);const installed = await readInstalledSkillTargets(skillsHome);return buildPersistentSkillSnapshot({@@ -57,7 +57,10 @@ export async function syncCursorSkills(desiredSkills: string[],): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);- const desiredSet = new Set(desiredSkills);+ const desiredSet = new Set([+ ...resolveLegacyPaperclipDesiredSkillNames({}, availableEntries),+ ...desiredSkills,+ ]);const skillsHome = resolveCursorSkillsHome(ctx.config);await fs.mkdir(skillsHome, { recursive: true });const installed = await readInstalledSkillTargets(skillsHome);@@ -84,5 +87,5 @@ export function resolveCursorDesiredSkillNames(config: Record<string, unknown>,availableEntries: Array<{ key: string }>,) {- return resolvePaperclipDesiredSkillNames(config, availableEntries);+ return resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);}diff --git a/packages/adapters/gemini-local/src/server/execute.ts b/packages/adapters/gemini-local/src/server/execute.tsindex ce01307b96..fb81512d79 100644--- a/packages/adapters/gemini-local/src/server/execute.ts+++ b/packages/adapters/gemini-local/src/server/execute.ts@@ -41,7 +41,7 @@ import {isPaperclipSkillSourceMissing,readPaperclipRuntimeSkillEntries,readPaperclipIssueWorkModeFromContext,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,removeMaintainerOnlySkillSymlinks,parseObject,renderTemplate,@@ -66,6 +66,7 @@ import {formatGeminiAcpFallbackMessage,resolveGeminiExecutionEngineForRun,} from "./acp.js";+import { resolveGeminiSkillsHome } from "./skills.js";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));const executeGeminiAcp = createGeminiAcpExecutor();@@ -132,25 +133,21 @@ function renderApiAccessNote(env: Record<string, string>): string {].join("\n");}-function geminiSkillsHome(): string {- return path.join(os.homedir(), ".gemini", "skills");-}-/**- * Inject Paperclip skills directly into `~/.gemini/skills/` via symlinks.+ * Inject Paperclip skills directly into the effective Gemini skills home.* This avoids needing GEMINI_CLI_HOME overrides, so the CLI naturally finds- * both its auth credentials and the injected skills in the real home directory.+ * both its auth credentials and the injected skills under the child HOME.*/async function ensureGeminiSkillsInjected(onLog: AdapterExecutionContext["onLog"],skillsEntries: Array<{ key: string; runtimeName: string; source: string }>,desiredSkillNames?: string[],+ skillsHome = resolveGeminiSkillsHome({}),): Promise<void> {const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.key));const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.key));if (selectedEntries.length === 0) return;- const skillsHome = geminiSkillsHome();try {await fs.mkdir(skillsHome, { recursive: true });} catch (err) {@@ -197,7 +194,7 @@ async function buildGeminiSkillsDir(const target = path.join(tmp, "skills");await fs.mkdir(target, { recursive: true });const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));+ const desiredNames = new Set(resolveLegacyPaperclipDesiredSkillNames(config, availableEntries));for (const entry of availableEntries) {if (!desiredNames.has(entry.key)) continue;if (isPaperclipSkillSourceMissing(entry)) continue;@@ -258,12 +255,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExeclet effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);await ensureAbsoluteDirectory(cwd, { createIfMissing: true });const geminiSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredGeminiSkillNames = resolvePaperclipDesiredSkillNames(config, geminiSkillEntries);+ const desiredGeminiSkillNames = resolveLegacyPaperclipDesiredSkillNames(config, geminiSkillEntries);if (!executionTargetIsRemote) {await ensureGeminiSkillsInjected(onLog,geminiSkillEntries.filter((entry) => !isPaperclipSkillSourceMissing(entry)),desiredGeminiSkillNames,+ resolveGeminiSkillsHome(config),);}diff --git a/packages/adapters/gemini-local/src/server/skills.ts b/packages/adapters/gemini-local/src/server/skills.tsindex 246d6eb44b..ea2ead2298 100644--- a/packages/adapters/gemini-local/src/server/skills.ts+++ b/packages/adapters/gemini-local/src/server/skills.ts@@ -11,7 +11,7 @@ import {ensurePaperclipSkillSymlink,readPaperclipRuntimeSkillEntries,readInstalledSkillTargets,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));@@ -20,7 +20,7 @@ function asString(value: unknown): string | null {return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;}-function resolveGeminiSkillsHome(config: Record<string, unknown>) {+export function resolveGeminiSkillsHome(config: Record<string, unknown>) {const env =typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)? (config.env as Record<string, unknown>)@@ -32,7 +32,7 @@ function resolveGeminiSkillsHome(config: Record<string, unknown>) {async function buildGeminiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const desiredSkills = resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);const skillsHome = resolveGeminiSkillsHome(config);const installed = await readInstalledSkillTargets(skillsHome);return buildPersistentSkillSnapshot({@@ -57,7 +57,10 @@ export async function syncGeminiSkills(desiredSkills: string[],): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);- const desiredSet = new Set(desiredSkills);+ const desiredSet = new Set([+ ...resolveLegacyPaperclipDesiredSkillNames({}, availableEntries),+ ...desiredSkills,+ ]);const skillsHome = resolveGeminiSkillsHome(ctx.config);await fs.mkdir(skillsHome, { recursive: true });const installed = await readInstalledSkillTargets(skillsHome);@@ -84,5 +87,5 @@ export function resolveGeminiDesiredSkillNames(config: Record<string, unknown>,availableEntries: Array<{ key: string }>,) {- return resolvePaperclipDesiredSkillNames(config, availableEntries);+ return resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);}diff --git a/packages/adapters/grok-local/src/server/execute.ts b/packages/adapters/grok-local/src/server/execute.tsindex 72ab25d6b0..ba2fef1a8b 100644--- a/packages/adapters/grok-local/src/server/execute.ts+++ b/packages/adapters/grok-local/src/server/execute.ts@@ -34,7 +34,7 @@ import {renderTemplate,renderPaperclipWakePrompt,isPaperclipRecoveryWakePayload,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,stringifyPaperclipWakePayload,refreshPaperclipWorkspaceEnvForExecution,DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,@@ -233,7 +233,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecawait ensureAbsoluteDirectory(cwd, { createIfMissing: true });const grokSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredGrokSkillNames = resolvePaperclipDesiredSkillNames(config, grokSkillEntries);+ const desiredGrokSkillNames = resolveLegacyPaperclipDesiredSkillNames(config, grokSkillEntries);const instructionsFilePath = asString(config.instructionsFilePath, "").trim();const stagedAssets = await stageGrokProjectAssets({cwd,diff --git a/packages/adapters/grok-local/src/server/skills.ts b/packages/adapters/grok-local/src/server/skills.tsindex dcfc038d65..10ee8d2f23 100644--- a/packages/adapters/grok-local/src/server/skills.ts+++ b/packages/adapters/grok-local/src/server/skills.ts@@ -7,7 +7,7 @@ import type {import {buildRuntimeMountedSkillSnapshot,readPaperclipRuntimeSkillEntries,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));@@ -16,7 +16,7 @@ async function buildGrokSkillSnapshot(config: Record<string, unknown>,): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const desiredSkills = resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);return buildRuntimeMountedSkillSnapshot({adapterType: "grok_local",availableEntries,diff --git a/packages/adapters/hermes/src/index.test.ts b/packages/adapters/hermes/src/index.test.tsindex 03e8809262..fec9fdf724 100644--- a/packages/adapters/hermes/src/index.test.ts+++ b/packages/adapters/hermes/src/index.test.ts@@ -1,3 +1,6 @@+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";import { expect, test } from "vitest";import {@@ -61,3 +64,93 @@ test("Hermes adapter exposes bundled Paperclip task bridge skill", async () => {expect(snapshot?.entries.some((entry) => entry.runtimeName === "paperclip-task-bridge")).toBe(true);});++test("Hermes keeps the operational Paperclip skill linked after an empty replacement", async () => {+ const home = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-hermes-core-skill-"));+ try {+ const source = path.join(home, "runtime-skills", "paperclip");+ await fs.mkdir(source, { recursive: true });+ await fs.writeFile(path.join(source, "SKILL.md"), "# Paperclip\n", "utf8");+ const adapter = createServerAdapter();+ const snapshot = await adapter.syncSkills?.({+ adapterType: "hermes_local",+ agentId: "11111111-1111-4111-8111-111111111111",+ companyId: "22222222-2222-4222-8222-222222222222",+ config: {+ env: { HOME: home },+ paperclipRuntimeSkills: [{+ key: "paperclipai/paperclip/paperclip",+ runtimeName: "paperclip",+ source,+ }],+ paperclipSkillSync: { desiredSkills: [] },+ },+ }, []);++ expect(snapshot?.desiredSkills).toContain("paperclipai/paperclip/paperclip");+ expect((await fs.lstat(path.join(home, ".hermes", "skills", "paperclip"))).isSymbolicLink()).toBe(true);+ } finally {+ await fs.rm(home, { recursive: true, force: true });+ }+});++test("Hermes rejects a conflicting operational skill target", async () => {+ const home = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-hermes-core-conflict-"));+ try {+ const source = path.join(home, "runtime-skills", "paperclip");+ const target = path.join(home, ".hermes", "skills", "paperclip");+ await fs.mkdir(source, { recursive: true });+ await fs.writeFile(path.join(source, "SKILL.md"), "# Paperclip\n", "utf8");+ await fs.mkdir(target, { recursive: true });+ await fs.writeFile(path.join(target, "SKILL.md"), "# Conflicting skill\n", "utf8");+ const adapter = createServerAdapter();++ await expect(adapter.syncSkills?.({+ adapterType: "hermes_local",+ agentId: "11111111-1111-4111-8111-111111111111",+ companyId: "22222222-2222-4222-8222-222222222222",+ config: {+ env: { HOME: home },+ paperclipRuntimeSkills: [{+ key: "paperclipai/paperclip/paperclip",+ runtimeName: "paperclip",+ source,+ }],+ },+ }, [])).rejects.toThrow("occupied by another installation");+ } finally {+ await fs.rm(home, { recursive: true, force: true });+ }+});++test("Hermes rejects a live symlink owned by another operational skill", async () => {+ const home = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-hermes-core-link-conflict-"));+ try {+ const source = path.join(home, "runtime-skills", "paperclip");+ const conflictingSource = path.join(home, "external-skills", "paperclip");+ const target = path.join(home, ".hermes", "skills", "paperclip");+ await fs.mkdir(source, { recursive: true });+ await fs.writeFile(path.join(source, "SKILL.md"), "# Paperclip\n", "utf8");+ await fs.mkdir(conflictingSource, { recursive: true });+ await fs.writeFile(path.join(conflictingSource, "SKILL.md"), "# External skill\n", "utf8");+ await fs.mkdir(path.dirname(target), { recursive: true });+ await fs.symlink(conflictingSource, target);+ const adapter = createServerAdapter();++ await expect(adapter.syncSkills?.({+ adapterType: "hermes_local",+ agentId: "11111111-1111-4111-8111-111111111111",+ companyId: "22222222-2222-4222-8222-222222222222",+ config: {+ env: { HOME: home },+ paperclipRuntimeSkills: [{+ key: "paperclipai/paperclip/paperclip",+ runtimeName: "paperclip",+ source,+ }],+ },+ }, [])).rejects.toThrow("occupied by another installation");+ } finally {+ await fs.rm(home, { recursive: true, force: true });+ }+});diff --git a/packages/adapters/hermes/src/server/execute.ts b/packages/adapters/hermes/src/server/execute.tsindex 3b4c5d4bc4..98b6b518cf 100644--- a/packages/adapters/hermes/src/server/execute.ts+++ b/packages/adapters/hermes/src/server/execute.ts@@ -52,6 +52,7 @@ import {detectModel,resolveProvider,} from "./detect-model.js";+import { reconcileHermesPaperclipSkills } from "./skills.js";// ---------------------------------------------------------------------------// Config helpers@@ -350,6 +351,25 @@ export async function execute((ctx.runtime?.sessionParams as Record<string, unknown> | null)?.sessionId,);+ // The server adds this runtime inventory at the run boundary. Requiring the+ // marker avoids touching a developer's real Hermes home in direct unit or+ // library calls that did not opt into Paperclip runtime skills.+ if (Object.prototype.hasOwnProperty.call(config, "paperclipRuntimeSkills")) {+ try {+ const selectedSkills = await reconcileHermesPaperclipSkills(config);+ if (selectedSkills.length > 0) {+ await ctx.onLog(+ "stdout",+ `[hermes] Reconciled ${selectedSkills.length} Paperclip-managed skill(s) into the Hermes skills home.\n`,+ );+ }+ } catch (err) {+ const reason = err instanceof Error ? err.message : String(err);+ await ctx.onLog("stderr", `[hermes] Cannot start without the required Paperclip-managed skills: ${reason}\n`);+ throw err;+ }+ }+// ── Resolve provider (defense in depth) ────────────────────────────────// Priority chain:// 1. Explicit provider in adapterConfig (user override)diff --git a/packages/adapters/hermes/src/server/skills.ts b/packages/adapters/hermes/src/server/skills.tsindex 6a9ea3c0d7..44e9453c45 100644--- a/packages/adapters/hermes/src/server/skills.ts+++ b/packages/adapters/hermes/src/server/skills.ts@@ -7,8 +7,11 @@ import type {AdapterSkillSnapshot,} from "@paperclipai/adapter-utils";import {+ ensurePaperclipSkillSymlink,+ isPaperclipSkillSourceMissing,+ readInstalledSkillTargets,readPaperclipRuntimeSkillEntries,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";import { fileURLToPath } from "node:url";@@ -132,7 +135,7 @@ async function buildHermesSkillSnapshot(config: Record<string, unknown>): Promis// 1. Scan Paperclip-managed skills (bundled with the adapter)const paperclipEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredSkills = resolvePaperclipDesiredSkillNames(config, paperclipEntries);+ const desiredSkills = resolveLegacyPaperclipDesiredSkillNames(config, paperclipEntries);const desiredSet = new Set(desiredSkills);const availableByKey = new Map(paperclipEntries.map((e) => [e.key, e]));@@ -209,12 +212,53 @@ export async function listHermesSkills(return buildHermesSkillSnapshot(ctx.config);}+export async function reconcileHermesPaperclipSkills(+ config: Record<string, unknown>,+ requestedDesiredSkills?: string[],+): Promise<string[]> {+ const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);+ const desiredSkills = requestedDesiredSkills+ ? Array.from(new Set([+ ...resolveLegacyPaperclipDesiredSkillNames({}, availableEntries),+ ...requestedDesiredSkills,+ ]))+ : resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);+ const desiredSet = new Set(desiredSkills);+ const skillsHome = path.join(resolveHermesHome(config), ".hermes", "skills");+ await fs.mkdir(skillsHome, { recursive: true });+ const installed = await readInstalledSkillTargets(skillsHome);+ const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));++ for (const entry of availableEntries) {+ if (!desiredSet.has(entry.key) || isPaperclipSkillSourceMissing(entry)) continue;+ const target = path.join(skillsHome, entry.runtimeName);+ await ensurePaperclipSkillSymlink(entry.source, target);+ const linkedSource = await fs.readlink(target).catch(() => null);+ const resolvedSource = linkedSource+ ? path.resolve(path.dirname(target), linkedSource)+ : null;+ if (resolvedSource !== path.resolve(entry.source)) {+ throw new Error(+ `Cannot reconcile Hermes skill "${entry.key}" because ${target} is occupied by another installation.`,+ );+ }+ }++ for (const [name, installedEntry] of installed.entries()) {+ const available = availableByRuntimeName.get(name);+ if (!available || desiredSet.has(available.key)) continue;+ if (installedEntry.targetPath !== available.source) continue;+ await fs.unlink(path.join(skillsHome, name)).catch(() => {});+ }++ return desiredSkills;+}+export async function syncHermesSkills(ctx: AdapterSkillContext,- _desiredSkills: string[],+ desiredSkills: string[],): Promise<AdapterSkillSnapshot> {- // Hermes manages its own skill loading — sync is a no-op.- // Return the current snapshot so the UI stays in sync.+ await reconcileHermesPaperclipSkills(ctx.config, desiredSkills);return buildHermesSkillSnapshot(ctx.config);}@@ -222,5 +266,5 @@ export function resolveHermesDesiredSkillNames(config: Record<string, unknown>,availableEntries: Array<{ key: string; runtimeName?: string | null }>,): string[] {- return resolvePaperclipDesiredSkillNames(config, availableEntries);+ return resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);}diff --git a/packages/adapters/kimi-local/src/server/execute.ts b/packages/adapters/kimi-local/src/server/execute.tsindex 4ec307bbca..5d16e37bde 100644--- a/packages/adapters/kimi-local/src/server/execute.ts+++ b/packages/adapters/kimi-local/src/server/execute.ts@@ -34,7 +34,7 @@ import {isPaperclipSkillSourceMissing,readPaperclipRuntimeSkillEntries,readPaperclipIssueWorkModeFromContext,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,parseObject,renderTemplate,renderPaperclipWakePrompt,@@ -174,7 +174,7 @@ async function buildKimiSkillsDir(const target = path.join(tmp, "skills");await fs.mkdir(target, { recursive: true });const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));+ const desiredNames = new Set(resolveLegacyPaperclipDesiredSkillNames(config, availableEntries));for (const entry of availableEntries) {if (!desiredNames.has(entry.key)) continue;if (isPaperclipSkillSourceMissing(entry)) continue;@@ -232,7 +232,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExeclet effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);await ensureAbsoluteDirectory(cwd, { createIfMissing: true });const kimiSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredKimiSkillNames = resolvePaperclipDesiredSkillNames(config, kimiSkillEntries);+ const desiredKimiSkillNames = resolveLegacyPaperclipDesiredSkillNames(config, kimiSkillEntries);const envConfig = parseObject(config.env);const hasExplicitApiKey =diff --git a/packages/adapters/kimi-local/src/server/skills.ts b/packages/adapters/kimi-local/src/server/skills.tsindex 5938b96315..72617f0269 100644--- a/packages/adapters/kimi-local/src/server/skills.ts+++ b/packages/adapters/kimi-local/src/server/skills.ts@@ -11,7 +11,7 @@ import {ensurePaperclipSkillSymlink,readPaperclipRuntimeSkillEntries,readInstalledSkillTargets,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));@@ -38,7 +38,7 @@ function resolveKimiSkillsHome(config: Record<string, unknown>) {async function buildKimiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const desiredSkills = resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);const skillsHome = resolveKimiSkillsHome(config);const installed = await readInstalledSkillTargets(skillsHome);return buildPersistentSkillSnapshot({@@ -63,7 +63,10 @@ export async function syncKimiSkills(desiredSkills: string[],): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);- const desiredSet = new Set(desiredSkills);+ const desiredSet = new Set([+ ...resolveLegacyPaperclipDesiredSkillNames({}, availableEntries),+ ...desiredSkills,+ ]);const skillsHome = resolveKimiSkillsHome(ctx.config);await fs.mkdir(skillsHome, { recursive: true });const installed = await readInstalledSkillTargets(skillsHome);diff --git a/packages/adapters/opencode-local/src/server/execute.test.ts b/packages/adapters/opencode-local/src/server/execute.test.tsindex 136cd6ca8a..74ec4d560a 100644--- a/packages/adapters/opencode-local/src/server/execute.test.ts+++ b/packages/adapters/opencode-local/src/server/execute.test.ts@@ -1,15 +1,25 @@import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";vi.mock("@paperclipai/adapter-utils/execution-target", async (importOriginal) => {const actual = (await importOriginal()) as Record<string, unknown>;return { ...actual, runAdapterExecutionTargetProcess: vi.fn() };});-import { ensureRemoteOpenCodeModelConfiguredAndAvailable } from "./execute.js";+import { ensureRemoteOpenCodeModelConfiguredAndAvailable, execute } from "./execute.js";import { runAdapterExecutionTargetProcess } from "@paperclipai/adapter-utils/execution-target";const runProcessMock = vi.mocked(runAdapterExecutionTargetProcess);+async function createSkillDir(root: string, name: string): Promise<string> {+ const skillDir = path.join(root, name);+ await fs.mkdir(skillDir, { recursive: true });+ await fs.writeFile(path.join(skillDir, "SKILL.md"), `# ${name}\n`, "utf8");+ return skillDir;+}+function probeResult(overrides: Record<string, unknown>) {return {exitCode: 0,@@ -23,6 +33,78 @@ function probeResult(overrides: Record<string, unknown>) {} as never;}+describe("OpenCode local skill injection", () => {+ it("injects runtime skills into the configured child HOME", async () => {+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-opencode-configured-home-"));+ const processHome = path.join(root, "process-home");+ const configuredHome = path.join(root, "configured-home");+ const workspace = path.join(root, "workspace");+ const commandPath = path.join(root, "opencode");+ const skillSource = await createSkillDir(path.join(root, "runtime-skills"), "paperclip");+ await fs.mkdir(workspace, { recursive: true });+ await fs.writeFile(commandPath, "#!/bin/sh\nexit 0\n", "utf8");+ await fs.chmod(commandPath, 0o755);++ const previousHome = process.env.HOME;+ process.env.HOME = processHome;+ runProcessMock.mockReset();+ runProcessMock.mockResolvedValueOnce(probeResult({+ stdout: JSON.stringify({+ type: "text",+ sessionID: "session-configured-home",+ part: { text: "done" },+ }),+ }));++ try {+ const result = await execute({+ runId: "run-configured-home",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "OpenCode Coder",+ adapterType: "opencode_local",+ adapterConfig: {},+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ command: commandPath,+ cwd: workspace,+ model: "openai/gpt-5",+ env: {+ HOME: configuredHome,+ OPENCODE_ALLOW_ALL_MODELS: "1",+ },+ paperclipRuntimeSkills: [{+ key: "paperclipai/paperclip/paperclip",+ runtimeName: "paperclip",+ source: skillSource,+ }],+ promptTemplate: "Follow the paperclip heartbeat.",+ },+ context: {},+ authToken: "run-jwt-token",+ onLog: async () => {},+ });++ expect(result.exitCode).toBe(0);+ const installedSkill = path.join(configuredHome, ".claude", "skills", "paperclip");+ expect((await fs.lstat(installedSkill)).isSymbolicLink()).toBe(true);+ expect(await fs.realpath(installedSkill)).toBe(await fs.realpath(skillSource));+ await expect(fs.lstat(path.join(processHome, ".claude", "skills", "paperclip"))).rejects.toThrow();+ } finally {+ if (previousHome === undefined) delete process.env.HOME;+ else process.env.HOME = previousHome;+ await fs.rm(root, { recursive: true, force: true });+ }+ });+});+describe("ensureRemoteOpenCodeModelConfiguredAndAvailable", () => {afterEach(() => {delete process.env.OPENCODE_ALLOW_ALL_MODELS;diff --git a/packages/adapters/opencode-local/src/server/execute.ts b/packages/adapters/opencode-local/src/server/execute.tsindex df3467511b..555a1d6757 100644--- a/packages/adapters/opencode-local/src/server/execute.ts+++ b/packages/adapters/opencode-local/src/server/execute.ts@@ -46,7 +46,7 @@ import {isPaperclipSkillSourceMissing,readPaperclipRuntimeSkillEntries,readPaperclipIssueWorkModeFromContext,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";import { isOpenCodeUnknownSessionError, parseOpenCodeJsonl } from "./parse.js";import {@@ -58,6 +58,7 @@ import {import { removeMaintainerOnlySkillSymlinks } from "@paperclipai/adapter-utils/server-utils";import { prepareOpenCodeRuntimeConfig } from "./runtime-config.js";import { SANDBOX_INSTALL_COMMAND } from "../index.js";+import { resolveOpenCodeSkillsHome } from "./skills.js";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));@@ -165,16 +166,12 @@ export async function ensureRemoteOpenCodeModelConfiguredAndAvailable(input: {}}-function claudeSkillsHome(): string {- return path.join(os.homedir(), ".claude", "skills");-}-async function ensureOpenCodeSkillsInjected(onLog: AdapterExecutionContext["onLog"],skillsEntries: Array<{ key: string; runtimeName: string; source: string }>,desiredSkillNames?: string[],+ skillsHome = resolveOpenCodeSkillsHome({}),) {- const skillsHome = claudeSkillsHome();await fs.mkdir(skillsHome, { recursive: true });const desiredSet = new Set(desiredSkillNames ?? skillsEntries.map((entry) => entry.key));const selectedEntries = skillsEntries.filter((entry) => desiredSet.has(entry.key));@@ -212,7 +209,7 @@ async function buildOpenCodeSkillsDir(config: Record<string, unknown>): Promise<const target = path.join(tmp, "skills");await fs.mkdir(target, { recursive: true });const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));+ const desiredNames = new Set(resolveLegacyPaperclipDesiredSkillNames(config, availableEntries));for (const entry of availableEntries) {if (!desiredNames.has(entry.key)) continue;if (isPaperclipSkillSourceMissing(entry)) continue;@@ -256,12 +253,13 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExeclet effectiveExecutionCwd = adapterExecutionTargetRemoteCwd(executionTarget, cwd);await ensureAbsoluteDirectory(cwd, { createIfMissing: true });const openCodeSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredOpenCodeSkillNames = resolvePaperclipDesiredSkillNames(config, openCodeSkillEntries);+ const desiredOpenCodeSkillNames = resolveLegacyPaperclipDesiredSkillNames(config, openCodeSkillEntries);if (!executionTargetIsRemote) {await ensureOpenCodeSkillsInjected(onLog,openCodeSkillEntries,desiredOpenCodeSkillNames,+ resolveOpenCodeSkillsHome(config),);}diff --git a/packages/adapters/opencode-local/src/server/skills.ts b/packages/adapters/opencode-local/src/server/skills.tsindex 1cd1f18a33..c2c91fc789 100644--- a/packages/adapters/opencode-local/src/server/skills.ts+++ b/packages/adapters/opencode-local/src/server/skills.ts@@ -11,7 +11,7 @@ import {ensurePaperclipSkillSymlink,readPaperclipRuntimeSkillEntries,readInstalledSkillTargets,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));@@ -20,7 +20,7 @@ function asString(value: unknown): string | null {return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;}-function resolveOpenCodeSkillsHome(config: Record<string, unknown>) {+export function resolveOpenCodeSkillsHome(config: Record<string, unknown>) {const env =typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)? (config.env as Record<string, unknown>)@@ -32,7 +32,7 @@ function resolveOpenCodeSkillsHome(config: Record<string, unknown>) {async function buildOpenCodeSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const desiredSkills = resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);const skillsHome = resolveOpenCodeSkillsHome(config);const installed = await readInstalledSkillTargets(skillsHome);return buildPersistentSkillSnapshot({@@ -61,7 +61,10 @@ export async function syncOpenCodeSkills(desiredSkills: string[],): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);- const desiredSet = new Set(desiredSkills);+ const desiredSet = new Set([+ ...resolveLegacyPaperclipDesiredSkillNames({}, availableEntries),+ ...desiredSkills,+ ]);const skillsHome = resolveOpenCodeSkillsHome(ctx.config);await fs.mkdir(skillsHome, { recursive: true });const installed = await readInstalledSkillTargets(skillsHome);@@ -88,5 +91,5 @@ export function resolveOpenCodeDesiredSkillNames(config: Record<string, unknown>,availableEntries: Array<{ key: string }>,) {- return resolvePaperclipDesiredSkillNames(config, availableEntries);+ return resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);}diff --git a/packages/adapters/pi-local/src/server/execute.ts b/packages/adapters/pi-local/src/server/execute.tsindex 9d3e50a35b..b601982033 100644--- a/packages/adapters/pi-local/src/server/execute.ts+++ b/packages/adapters/pi-local/src/server/execute.ts@@ -40,7 +40,7 @@ import {isPaperclipSkillSourceMissing,readPaperclipRuntimeSkillEntries,readPaperclipIssueWorkModeFromContext,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,removeMaintainerOnlySkillSymlinks,renderTemplate,renderPaperclipWakePrompt,@@ -127,7 +127,7 @@ async function buildPiSkillsDir(config: Record<string, unknown>): Promise<stringconst target = path.join(tmp, "skills");await fs.mkdir(target, { recursive: true });const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredNames = new Set(resolvePaperclipDesiredSkillNames(config, availableEntries));+ const desiredNames = new Set(resolveLegacyPaperclipDesiredSkillNames(config, availableEntries));for (const entry of availableEntries) {if (!desiredNames.has(entry.key)) continue;if (isPaperclipSkillSourceMissing(entry)) continue;@@ -261,7 +261,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec}const piSkillEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredPiSkillNames = resolvePaperclipDesiredSkillNames(config, piSkillEntries);+ const desiredPiSkillNames = resolveLegacyPaperclipDesiredSkillNames(config, piSkillEntries);if (!executionTargetIsRemote) {await ensurePiSkillsInjected(onLog, piSkillEntries, desiredPiSkillNames);}diff --git a/packages/adapters/pi-local/src/server/skills.ts b/packages/adapters/pi-local/src/server/skills.tsindex cae3915b74..de9a3be8d9 100644--- a/packages/adapters/pi-local/src/server/skills.ts+++ b/packages/adapters/pi-local/src/server/skills.ts@@ -11,7 +11,7 @@ import {ensurePaperclipSkillSymlink,readPaperclipRuntimeSkillEntries,readInstalledSkillTargets,- resolvePaperclipDesiredSkillNames,+ resolveLegacyPaperclipDesiredSkillNames,} from "@paperclipai/adapter-utils/server-utils";const __moduleDir = path.dirname(fileURLToPath(import.meta.url));@@ -32,7 +32,7 @@ function resolvePiSkillsHome(config: Record<string, unknown>) {async function buildPiSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);- const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);+ const desiredSkills = resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);const skillsHome = resolvePiSkillsHome(config);const installed = await readInstalledSkillTargets(skillsHome);return buildPersistentSkillSnapshot({@@ -57,7 +57,10 @@ export async function syncPiSkills(desiredSkills: string[],): Promise<AdapterSkillSnapshot> {const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);- const desiredSet = new Set(desiredSkills);+ const desiredSet = new Set([+ ...resolveLegacyPaperclipDesiredSkillNames({}, availableEntries),+ ...desiredSkills,+ ]);const skillsHome = resolvePiSkillsHome(ctx.config);await fs.mkdir(skillsHome, { recursive: true });const installed = await readInstalledSkillTargets(skillsHome);@@ -84,5 +87,5 @@ export function resolvePiDesiredSkillNames(config: Record<string, unknown>,availableEntries: Array<{ key: string }>,) {- return resolvePaperclipDesiredSkillNames(config, availableEntries);+ return resolveLegacyPaperclipDesiredSkillNames(config, availableEntries);}diff --git a/server/src/__tests__/claude-local-skill-sync.test.ts b/server/src/__tests__/claude-local-skill-sync.test.tsindex ce5b428470..eeec299135 100644--- a/server/src/__tests__/claude-local-skill-sync.test.ts+++ b/server/src/__tests__/claude-local-skill-sync.test.ts@@ -28,7 +28,7 @@ describe("claude local skill sync", () => {cleanupDirs.clear();});- it("reports built-in Paperclip skills as available when no explicit selection exists", async () => {+ it("keeps the operational Paperclip skill configured when no explicit selection exists", async () => {const snapshot = await listClaudeSkills({agentId: "agent-1",companyId: "company-1",@@ -38,8 +38,9 @@ describe("claude local skill sync", () => {expect(snapshot.mode).toBe("ephemeral");expect(snapshot.supported).toBe(true);- expect(snapshot.desiredSkills).toEqual([]);- expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("available");+ expect(snapshot.desiredSkills).toEqual([paperclipKey]);+ expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("configured");+ expect(snapshot.entries.find((entry) => entry.key === createAgentKey)?.state).toBe("available");});it("respects an explicit desired skill list without mutating a persistent home", async () => {diff --git a/server/src/__tests__/codex-local-execute.test.ts b/server/src/__tests__/codex-local-execute.test.tsindex a907119970..841b7d6fa7 100644--- a/server/src/__tests__/codex-local-execute.test.ts+++ b/server/src/__tests__/codex-local-execute.test.ts@@ -1322,7 +1322,7 @@ process.exit(1);await fs.rm(root, { recursive: true, force: true });}});- it("uses a worktree-isolated CODEX_HOME while preserving shared auth and config", async () => {+ it("uses a worktree-isolated CODEX_HOME and mounts the operational skill by default", async () => {const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-codex-execute-"));const workspace = path.join(root, "workspace");const commandPath = path.join(root, "codex");@@ -1380,9 +1380,6 @@ process.exit(1);PAPERCLIP_TEST_CAPTURE_PATH: capturePath,},promptTemplate: "Follow the paperclip heartbeat.",- paperclipSkillSync: {- desiredSkills: ["paperclip"],- },},context: {},authToken: "run-jwt-token",diff --git a/server/src/__tests__/codex-local-skill-sync.test.ts b/server/src/__tests__/codex-local-skill-sync.test.tsindex 94862a0147..17750781b8 100644--- a/server/src/__tests__/codex-local-skill-sync.test.ts+++ b/server/src/__tests__/codex-local-skill-sync.test.ts@@ -20,7 +20,7 @@ describe("codex local skill sync", () => {cleanupDirs.clear();});- it("reports configured Paperclip skills for workspace injection on the next run", async () => {+ it("defaults the operational Paperclip skill for workspace injection on the next run", async () => {const codexHome = await makeTempDir("paperclip-codex-skill-sync-");cleanupDirs.add(codexHome);@@ -32,9 +32,6 @@ describe("codex local skill sync", () => {env: {CODEX_HOME: codexHome,},- paperclipSkillSync: {- desiredSkills: [paperclipKey],- },},} as const;@@ -45,6 +42,19 @@ describe("codex local skill sync", () => {expect(before.entries.find((entry) => entry.key === paperclipKey)?.detail).toContain("CODEX_HOME/skills/");});+ it("does not apply the legacy operational skill default to the native runner", async () => {+ const snapshot = await listCodexSkills({+ agentId: "agent-native",+ companyId: "company-1",+ adapterType: "paperclip_runner",+ config: {},+ });++ expect(snapshot.adapterType).toBe("paperclip_runner");+ expect(snapshot.desiredSkills).toEqual([]);+ expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("available");+ });+it("does not persist Paperclip skills into CODEX_HOME during sync", async () => {const codexHome = await makeTempDir("paperclip-codex-skill-prune-");cleanupDirs.add(codexHome);diff --git a/server/src/__tests__/cursor-local-execute.test.ts b/server/src/__tests__/cursor-local-execute.test.tsindex e37f12b478..ac0c848061 100644--- a/server/src/__tests__/cursor-local-execute.test.ts+++ b/server/src/__tests__/cursor-local-execute.test.ts@@ -252,6 +252,8 @@ describe("cursor execute", () => {it("injects company-library runtime skills into the Cursor skills home before execution", async () => {const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-cursor-execute-runtime-skill-"));+ const processHome = path.join(root, "process-home");+ const configuredHome = path.join(root, "configured-home");const workspace = path.join(root, "workspace");const commandPath = path.join(root, "agent");const runtimeSkillsRoot = path.join(root, "runtime-skills");@@ -262,7 +264,7 @@ describe("cursor execute", () => {const asciiHeartDir = await createSkillDir(runtimeSkillsRoot, "ascii-heart");const previousHome = process.env.HOME;- process.env.HOME = root;+ process.env.HOME = processHome;try {const result = await execute({@@ -284,6 +286,7 @@ describe("cursor execute", () => {command: commandPath,cwd: workspace,model: "auto",+ env: { HOME: configuredHome },paperclipRuntimeSkills: [{name: "paperclip",@@ -307,10 +310,12 @@ describe("cursor execute", () => {expect(result.exitCode).toBe(0);expect(result.errorMessage).toBeNull();- expect((await fs.lstat(path.join(root, ".cursor", "skills", "ascii-heart"))).isSymbolicLink()).toBe(true);- expect(await fs.realpath(path.join(root, ".cursor", "skills", "ascii-heart"))).toBe(+ const installedSkill = path.join(configuredHome, ".cursor", "skills", "ascii-heart");+ expect((await fs.lstat(installedSkill)).isSymbolicLink()).toBe(true);+ expect(await fs.realpath(installedSkill)).toBe(await fs.realpath(asciiHeartDir),);+ await expect(fs.lstat(path.join(processHome, ".cursor", "skills", "ascii-heart"))).rejects.toThrow();} finally {if (previousHome === undefined) {delete process.env.HOME;diff --git a/server/src/__tests__/cursor-local-skill-sync.test.ts b/server/src/__tests__/cursor-local-skill-sync.test.tsindex 3660f8b203..5f188fa022 100644--- a/server/src/__tests__/cursor-local-skill-sync.test.ts+++ b/server/src/__tests__/cursor-local-skill-sync.test.ts@@ -27,7 +27,7 @@ describe("cursor local skill sync", () => {cleanupDirs.clear();});- it("reports configured Paperclip skills and installs them into the Cursor skills home", async () => {+ it("defaults and installs the operational Paperclip skill in the Cursor skills home", async () => {const home = await makeTempDir("paperclip-cursor-skill-sync-");cleanupDirs.add(home);@@ -39,9 +39,6 @@ describe("cursor local skill sync", () => {env: {HOME: home,},- paperclipSkillSync: {- desiredSkills: [paperclipKey],- },},} as const;@@ -55,6 +52,25 @@ describe("cursor local skill sync", () => {expect((await fs.lstat(path.join(home, ".cursor", "skills", "paperclip"))).isSymbolicLink()).toBe(true);});+ it("keeps the operational skill installed after an explicit empty replacement", async () => {+ const home = await makeTempDir("paperclip-cursor-required-skill-");+ cleanupDirs.add(home);++ const snapshot = await syncCursorSkills({+ agentId: "agent-required",+ companyId: "company-1",+ adapterType: "cursor",+ config: {+ env: { HOME: home },+ paperclipSkillSync: { desiredSkills: [] },+ },+ }, []);++ expect(snapshot.desiredSkills).toEqual([paperclipKey]);+ expect(snapshot.entries.find((entry) => entry.key === paperclipKey)?.state).toBe("installed");+ expect((await fs.lstat(path.join(home, ".cursor", "skills", "paperclip"))).isSymbolicLink()).toBe(true);+ });+it("recognizes company-library runtime skills supplied outside the bundled Paperclip directory", async () => {const home = await makeTempDir("paperclip-cursor-runtime-skills-home-");const runtimeSkills = await makeTempDir("paperclip-cursor-runtime-skills-src-");diff --git a/server/src/__tests__/gemini-local-execute.test.ts b/server/src/__tests__/gemini-local-execute.test.tsindex 83924852a5..80fc5d8eb8 100644--- a/server/src/__tests__/gemini-local-execute.test.ts+++ b/server/src/__tests__/gemini-local-execute.test.ts@@ -73,7 +73,72 @@ type CapturePayload = {paperclipEnvKeys: string[];};+async function createSkillDir(root: string, name: string): Promise<string> {+ const skillDir = path.join(root, name);+ await fs.mkdir(skillDir, { recursive: true });+ await fs.writeFile(path.join(skillDir, "SKILL.md"), `# ${name}\n`, "utf8");+ return skillDir;+}+describe("gemini execute", () => {+ it("injects runtime skills into the configured child HOME", async () => {+ const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-gemini-configured-home-"));+ const processHome = path.join(root, "process-home");+ const configuredHome = path.join(root, "configured-home");+ const workspace = path.join(root, "workspace");+ const commandPath = path.join(root, "gemini");+ const skillSource = await createSkillDir(path.join(root, "runtime-skills"), "paperclip");+ await fs.mkdir(workspace, { recursive: true });+ await writeFakeGeminiCommand(commandPath);++ const previousHome = process.env.HOME;+ process.env.HOME = processHome;++ try {+ const result = await execute({+ runId: "run-configured-home",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Gemini Coder",+ adapterType: "gemini_local",+ adapterConfig: { engine: "cli" },+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config: {+ engine: "cli",+ command: commandPath,+ cwd: workspace,+ env: { HOME: configuredHome },+ paperclipRuntimeSkills: [{+ key: "paperclipai/paperclip/paperclip",+ runtimeName: "paperclip",+ source: skillSource,+ }],+ promptTemplate: "Follow the paperclip heartbeat.",+ },+ context: {},+ authToken: "run-jwt-token",+ onLog: async () => {},+ });++ expect(result.exitCode).toBe(0);+ const installedSkill = path.join(configuredHome, ".gemini", "skills", "paperclip");+ expect((await fs.lstat(installedSkill)).isSymbolicLink()).toBe(true);+ expect(await fs.realpath(installedSkill)).toBe(await fs.realpath(skillSource));+ await expect(fs.lstat(path.join(processHome, ".gemini", "skills", "paperclip"))).rejects.toThrow();+ } finally {+ if (previousHome === undefined) delete process.env.HOME;+ else process.env.HOME = previousHome;+ await fs.rm(root, { recursive: true, force: true });+ }+ });+it("passes prompt via --prompt and injects paperclip env vars", async () => {const root = await fs.mkdtemp(path.join(os.tmpdir(), "paperclip-gemini-execute-"));const workspace = path.join(root, "workspace");diff --git a/server/src/__tests__/gemini-local-skill-sync.test.ts b/server/src/__tests__/gemini-local-skill-sync.test.tsindex 646ac45a16..c5a5ec2958 100644--- a/server/src/__tests__/gemini-local-skill-sync.test.ts+++ b/server/src/__tests__/gemini-local-skill-sync.test.ts@@ -20,7 +20,7 @@ describe("gemini local skill sync", () => {cleanupDirs.clear();});- it("reports configured Paperclip skills and installs them into the Gemini skills home", async () => {+ it("defaults and installs the operational Paperclip skill in the Gemini skills home", async () => {const home = await makeTempDir("paperclip-gemini-skill-sync-");cleanupDirs.add(home);@@ -32,9 +32,6 @@ describe("gemini local skill sync", () => {env: {HOME: home,},- paperclipSkillSync: {- desiredSkills: [paperclipKey],- },},} as const;diff --git a/server/src/__tests__/grok-local-skill-sync.test.ts b/server/src/__tests__/grok-local-skill-sync.test.tsindex 64c0fe769d..8c2aa0e927 100644--- a/server/src/__tests__/grok-local-skill-sync.test.ts+++ b/server/src/__tests__/grok-local-skill-sync.test.ts@@ -7,16 +7,12 @@ import {describe("grok local skill sync", () => {const paperclipKey = "paperclipai/paperclip/paperclip";- it("reports Grok skills as ephemeral workspace-mounted state", async () => {+ it("defaults the operational Paperclip skill as ephemeral workspace-mounted state", async () => {const snapshot = await listGrokSkills({agentId: "agent-1",companyId: "company-1",adapterType: "grok_local",- config: {- paperclipSkillSync: {- desiredSkills: [paperclipKey],- },- },+ config: {},});expect(snapshot.adapterType).toBe("grok_local");diff --git a/server/src/__tests__/kimi-local-skill-sync.test.ts b/server/src/__tests__/kimi-local-skill-sync.test.tsindex 7bb904252a..f88f144f74 100644--- a/server/src/__tests__/kimi-local-skill-sync.test.ts+++ b/server/src/__tests__/kimi-local-skill-sync.test.ts@@ -20,7 +20,7 @@ describe("kimi local skill sync", () => {cleanupDirs.clear();});- it("reports configured Paperclip skills and installs them into the Kimi skills home", async () => {+ it("defaults and installs the operational Paperclip skill in the Kimi skills home", async () => {const kimiCodeHome = await makeTempDir("paperclip-kimi-skill-sync-");cleanupDirs.add(kimiCodeHome);@@ -32,9 +32,6 @@ describe("kimi local skill sync", () => {env: {KIMI_CODE_HOME: kimiCodeHome,},- paperclipSkillSync: {- desiredSkills: [paperclipKey],- },},} as const;diff --git a/server/src/__tests__/opencode-local-skill-sync.test.ts b/server/src/__tests__/opencode-local-skill-sync.test.tsindex 48d97523c9..c07c5940c5 100644--- a/server/src/__tests__/opencode-local-skill-sync.test.ts+++ b/server/src/__tests__/opencode-local-skill-sync.test.ts@@ -20,7 +20,7 @@ describe("opencode local skill sync", () => {cleanupDirs.clear();});- it("reports configured Paperclip skills and installs them into the shared Claude/OpenCode skills home", async () => {+ it("defaults and installs the operational Paperclip skill in the shared Claude/OpenCode skills home", async () => {const home = await makeTempDir("paperclip-opencode-skill-sync-");cleanupDirs.add(home);@@ -32,9 +32,6 @@ describe("opencode local skill sync", () => {env: {HOME: home,},- paperclipSkillSync: {- desiredSkills: [paperclipKey],- },},} as const;diff --git a/server/src/__tests__/pi-local-execute.test.ts b/server/src/__tests__/pi-local-execute.test.tsindex f9fe2d3ff7..265a26800f 100644--- a/server/src/__tests__/pi-local-execute.test.ts+++ b/server/src/__tests__/pi-local-execute.test.ts@@ -188,8 +188,8 @@ describe("pi_local execute", () => {cwd: workspace,model: "google/gemini-3-flash-preview",promptTemplate: "Keep working.",- // No explicit paperclipSkillSync preference →- // resolvePaperclipDesiredSkillNames returns [] → skill is not injected.+ // The implicit legacy default applies only to the canonical Paperclip+ // operational skill, so this unrelated skill remains unselected.paperclipRuntimeSkills: [{ key: "not-injected", runtimeName: "not-injected", source: nonInjectedSkillDir },],diff --git a/server/src/__tests__/pi-local-skill-sync.test.ts b/server/src/__tests__/pi-local-skill-sync.test.tsindex a49b202e32..4019ae5de4 100644--- a/server/src/__tests__/pi-local-skill-sync.test.ts+++ b/server/src/__tests__/pi-local-skill-sync.test.ts@@ -20,7 +20,7 @@ describe("pi local skill sync", () => {cleanupDirs.clear();});- it("reports configured Paperclip skills and installs them into the Pi skills home", async () => {+ it("defaults and installs the operational Paperclip skill in the Pi skills home", async () => {const home = await makeTempDir("paperclip-pi-skill-sync-");cleanupDirs.add(home);@@ -32,9 +32,6 @@ describe("pi local skill sync", () => {env: {HOME: home,},- paperclipSkillSync: {- desiredSkills: [paperclipKey],- },},} as const;diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.tsindex fbdc97b0ae..cb510ce4d3 100644--- a/server/src/routes/agents.ts+++ b/server/src/routes/agents.ts@@ -2227,8 +2227,9 @@ export function agentRoutes(// The default CEO instructions assume the core paperclip skills (board// coordination, planning, hiring, memory). Union them into every// skills-capable CEO hire/create so a fresh CEO never starts with an empty- // desired-skill set that contradicts its own instructions. Callers can still- // remove any of them afterwards via the per-agent skills sync.+ // desired-skill set that contradicts its own instructions. Optional role+ // skills remain removable afterwards. Legacy adapters separately guarantee+ // the Paperclip operational skill as a runtime invariant.function defaultRoleSkillSelections(role: string | null | undefined,adapterType: string,