Add adapter skill sync for codex and claude

packages/adapters/claude-local/src/server/execute.ts

@@ -12,6 +12,7 @@ import {
   parseObject,
   parseJson,
   buildPaperclipEnv,
+  listPaperclipSkillEntries,
   joinPromptSections,
   redactEnvForLogs,
   ensureAbsoluteDirectory,
@@ -27,40 +28,32 @@ import {
   isClaudeMaxTurnsResult,
   isClaudeUnknownSessionError,
 } from "./parse.js";
+import { resolveClaudeDesiredSkillNames } from "./skills.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
-const PAPERCLIP_SKILLS_CANDIDATES = [
-  path.resolve(__moduleDir, "../../skills"),         // published: <pkg>/dist/server/ -> <pkg>/skills/
-  path.resolve(__moduleDir, "../../../../../skills"), // dev: src/server/ -> repo root/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;
-}
 
 /**
  * Create a tmpdir with `.claude/skills/` containing symlinks to skills from
  * the repo's `skills/` directory, so `--add-dir` makes Claude Code discover
  * them as proper registered skills.
  */
-async function buildSkillsDir(): Promise<string> {
+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 skillsDir = await resolvePaperclipSkillsDir();
-  if (!skillsDir) return tmp;
-  const entries = await fs.readdir(skillsDir, { withFileTypes: true });
-  for (const entry of entries) {
-    if (entry.isDirectory()) {
-      await fs.symlink(
-        path.join(skillsDir, entry.name),
-        path.join(target, entry.name),
-      );
-    }
+  const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+  const desiredNames = new Set(
+    resolveClaudeDesiredSkillNames(
+      config,
+      availableEntries.map((entry) => entry.name),
+    ),
+  );
+  for (const entry of availableEntries) {
+    if (!desiredNames.has(entry.name)) continue;
+    await fs.symlink(
+      entry.source,
+      path.join(target, entry.name),
+    );
   }
   return tmp;
 }
@@ -337,7 +330,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     extraArgs,
   } = runtimeConfig;
   const billingType = resolveClaudeBillingType(env);
-  const skillsDir = await buildSkillsDir();
+  const skillsDir = await buildSkillsDir(config);
 
   // When instructionsFilePath is configured, create a combined temp file that
   // includes both the file content and the path directive, so we only need

packages/adapters/claude-local/src/server/index.ts

@@ -1,4 +1,5 @@
 export { execute, runClaudeLogin } from "./execute.js";
+export { listClaudeSkills, syncClaudeSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export {
   parseClaudeStreamJson,

packages/adapters/claude-local/src/server/skills.ts

@@ -0,0 +1,83 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillEntry,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  listPaperclipSkillEntries,
+  readPaperclipSkillSyncPreference,
+} 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 availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
+  const desiredSkills = resolveDesiredSkillNames(
+    config,
+    availableEntries.map((entry) => entry.name),
+  );
+  const desiredSet = new Set(desiredSkills);
+  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
+    name: entry.name,
+    desired: desiredSet.has(entry.name),
+    managed: true,
+    state: desiredSet.has(entry.name) ? "configured" : "available",
+    sourcePath: entry.source,
+    targetPath: null,
+    detail: desiredSet.has(entry.name)
+      ? "Will be mounted into the ephemeral Claude skill directory on the next run."
+      : null,
+  }));
+  const warnings: string[] = [];
+
+  for (const desiredSkill of desiredSkills) {
+    if (availableByName.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      name: desiredSkill,
+      desired: true,
+      managed: true,
+      state: "missing",
+      sourcePath: undefined,
+      targetPath: undefined,
+      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+    });
+  }
+
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+
+  return {
+    adapterType: "claude_local",
+    supported: true,
+    mode: "ephemeral",
+    desiredSkills,
+    entries,
+    warnings,
+  };
+}
+
+export async function listClaudeSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildClaudeSkillSnapshot(ctx.config);
+}
+
+export async function syncClaudeSkills(
+  ctx: AdapterSkillContext,
+  _desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  return buildClaudeSkillSnapshot(ctx.config);
+}
+
+export function resolveClaudeDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableSkillNames: string[],
+) {
+  return resolveDesiredSkillNames(config, availableSkillNames);
+}

packages/adapters/codex-local/src/server/execute.ts

@@ -22,6 +22,7 @@ import {
 } from "@paperclipai/adapter-utils/server-utils";
 import { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
 import { pathExists, prepareWorktreeCodexHome, resolveCodexHomeDir } from "./codex-home.js";
+import { resolveCodexDesiredSkillNames } from "./skills.js";
 
 const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
 const CODEX_ROLLOUT_NOISE_RE =
@@ -92,6 +93,7 @@ async function isLikelyPaperclipRuntimeSkillSource(candidate: string, skillName:
 type EnsureCodexSkillsInjectedOptions = {
   skillsHome?: string;
   skillsEntries?: Awaited<ReturnType<typeof listPaperclipSkillEntries>>;
+  desiredSkillNames?: string[];
   linkSkill?: (source: string, target: string) => Promise<void>;
 };
 
@@ -99,7 +101,11 @@ export async function ensureCodexSkillsInjected(
   onLog: AdapterExecutionContext["onLog"],
   options: EnsureCodexSkillsInjectedOptions = {},
 ) {
-  const skillsEntries = options.skillsEntries ?? await listPaperclipSkillEntries(__moduleDir);
+  const allSkillsEntries = options.skillsEntries ?? await listPaperclipSkillEntries(__moduleDir);
+  const desiredSkillNames =
+    options.desiredSkillNames ?? allSkillsEntries.map((entry) => entry.name);
+  const desiredSet = new Set(desiredSkillNames);
+  const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.name));
   if (skillsEntries.length === 0) return;
 
   const skillsHome = options.skillsHome ?? path.join(resolveCodexHomeDir(process.env), "skills");
@@ -213,13 +219,22 @@ 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),
+  );
   await ensureAbsoluteDirectory(cwd, { createIfMissing: true });
   const preparedWorktreeCodexHome =
     configuredCodexHome ? null : await prepareWorktreeCodexHome(process.env, onLog);
   const effectiveCodexHome = configuredCodexHome ?? preparedWorktreeCodexHome;
   await ensureCodexSkillsInjected(
     onLog,
-    effectiveCodexHome ? { skillsHome: path.join(effectiveCodexHome, "skills") } : {},
+    effectiveCodexHome
+      ? {
+          skillsHome: path.join(effectiveCodexHome, "skills"),
+          desiredSkillNames,
+        }
+      : { desiredSkillNames },
   );
   const hasExplicitApiKey =
     typeof envConfig.PAPERCLIP_API_KEY === "string" && envConfig.PAPERCLIP_API_KEY.trim().length > 0;

packages/adapters/codex-local/src/server/index.ts

@@ -1,4 +1,5 @@
 export { execute, ensureCodexSkillsInjected } from "./execute.js";
+export { listCodexSkills, syncCodexSkills } from "./skills.js";
 export { testEnvironment } from "./test.js";
 export { parseCodexJsonl, isCodexUnknownSessionError } from "./parse.js";
 import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";

packages/adapters/codex-local/src/server/skills.ts

@@ -0,0 +1,179 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import type {
+  AdapterSkillContext,
+  AdapterSkillEntry,
+  AdapterSkillSnapshot,
+} from "@paperclipai/adapter-utils";
+import {
+  ensurePaperclipSkillSymlink,
+  listPaperclipSkillEntries,
+  readPaperclipSkillSyncPreference,
+} from "@paperclipai/adapter-utils/server-utils";
+import { resolveCodexHomeDir } from "./codex-home.js";
+
+const __moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+function asString(value: unknown): string | null {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+
+function resolveCodexSkillsHome(config: Record<string, unknown>) {
+  const env =
+    typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)
+      ? (config.env as Record<string, unknown>)
+      : {};
+  const configuredCodexHome = asString(env.CODEX_HOME);
+  const home = configuredCodexHome ? path.resolve(configuredCodexHome) : resolveCodexHomeDir(process.env);
+  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" }>();
+  for (const entry of entries) {
+    const fullPath = path.join(skillsHome, entry.name);
+    if (entry.isSymbolicLink()) {
+      const linkedPath = await fs.readlink(fullPath).catch(() => null);
+      out.set(entry.name, {
+        targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
+        kind: "symlink",
+      });
+      continue;
+    }
+    if (entry.isDirectory()) {
+      out.set(entry.name, { targetPath: fullPath, kind: "directory" });
+      continue;
+    }
+    out.set(entry.name, { targetPath: fullPath, kind: "file" });
+  }
+  return out;
+}
+
+async function buildCodexSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+  const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
+  const desiredSkills = resolveDesiredSkillNames(
+    config,
+    availableEntries.map((entry) => entry.name),
+  );
+  const desiredSet = new Set(desiredSkills);
+  const skillsHome = resolveCodexSkillsHome(config);
+  const installed = await readInstalledSkillTargets(skillsHome);
+  const entries: AdapterSkillEntry[] = [];
+  const warnings: string[] = [];
+
+  for (const available of availableEntries) {
+    const installedEntry = installed.get(available.name) ?? null;
+    const desired = desiredSet.has(available.name);
+    let state: AdapterSkillEntry["state"] = "available";
+    let managed = false;
+    let detail: string | null = null;
+
+    if (installedEntry?.targetPath === available.source) {
+      managed = true;
+      state = desired ? "installed" : "stale";
+    } else if (installedEntry) {
+      state = "external";
+      detail = desired
+        ? "Skill name is occupied by an external installation."
+        : "Installed outside Paperclip management.";
+    } else if (desired) {
+      state = "missing";
+      detail = "Configured but not currently linked into the Codex skills home.";
+    }
+
+    entries.push({
+      name: available.name,
+      desired,
+      managed,
+      state,
+      sourcePath: available.source,
+      targetPath: path.join(skillsHome, available.name),
+      detail,
+    });
+  }
+
+  for (const desiredSkill of desiredSkills) {
+    if (availableByName.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      name: desiredSkill,
+      desired: true,
+      managed: true,
+      state: "missing",
+      sourcePath: null,
+      targetPath: path.join(skillsHome, desiredSkill),
+      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+    });
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    if (availableByName.has(name)) continue;
+    entries.push({
+      name,
+      desired: false,
+      managed: false,
+      state: "external",
+      sourcePath: null,
+      targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
+      detail: "Installed outside Paperclip management.",
+    });
+  }
+
+  entries.sort((left, right) => left.name.localeCompare(right.name));
+
+  return {
+    adapterType: "codex_local",
+    supported: true,
+    mode: "persistent",
+    desiredSkills,
+    entries,
+    warnings,
+  };
+}
+
+export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
+  return buildCodexSkillSnapshot(ctx.config);
+}
+
+export async function syncCodexSkills(
+  ctx: AdapterSkillContext,
+  desiredSkills: string[],
+): Promise<AdapterSkillSnapshot> {
+  const availableEntries = await listPaperclipSkillEntries(__moduleDir);
+  const desiredSet = new Set(desiredSkills);
+  const skillsHome = resolveCodexSkillsHome(ctx.config);
+  await fs.mkdir(skillsHome, { recursive: true });
+  const installed = await readInstalledSkillTargets(skillsHome);
+  const availableByName = new Map(availableEntries.map((entry) => [entry.name, entry]));
+
+  for (const available of availableEntries) {
+    if (!desiredSet.has(available.name)) continue;
+    const target = path.join(skillsHome, available.name);
+    await ensurePaperclipSkillSymlink(available.source, target);
+  }
+
+  for (const [name, installedEntry] of installed.entries()) {
+    const available = availableByName.get(name);
+    if (!available) continue;
+    if (desiredSet.has(name)) continue;
+    if (installedEntry.targetPath !== available.source) continue;
+    await fs.unlink(path.join(skillsHome, name)).catch(() => {});
+  }
+
+  return buildCodexSkillSnapshot(ctx.config);
+}
+
+export function resolveCodexDesiredSkillNames(
+  config: Record<string, unknown>,
+  availableSkillNames: string[],
+) {
+  return resolveDesiredSkillNames(config, availableSkillNames);
+}