Refine codex runtime skills and portability assets

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

@@ -40,7 +40,7 @@ Operational fields:
 
 Notes:
 - Prompts are piped via stdin (Codex receives "-" prompt argument).
-- Paperclip auto-injects local skills into Codex personal skills dir ("$CODEX_HOME/skills" or "~/.codex/skills") when missing, so Codex can discover "$paperclip" and related skills.
+- Paperclip injects desired local skills into the active workspace's ".agents/skills" directory at execution time so Codex can discover "$paperclip" and related skills without coupling them to the user's login home.
 - Some model/tool combinations reject certain effort levels (for example minimal with web search enabled).
 - When Paperclip realizes a workspace/runtime for a run, it injects PAPERCLIP_WORKSPACE_* and PAPERCLIP_RUNTIME_* env vars for agent-side tooling.
 `;

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

@@ -16,7 +16,6 @@ import {
   ensurePathInEnv,
   readPaperclipRuntimeSkillEntries,
   resolvePaperclipDesiredSkillNames,
-  removeMaintainerOnlySkillSymlinks,
   renderTemplate,
   joinPromptSections,
   runChildProcess,
@@ -136,6 +135,10 @@ async function pruneBrokenUnavailablePaperclipSkillSymlinks(
   }
 }
 
+function resolveCodexWorkspaceSkillsDir(cwd: string): string {
+  return path.join(cwd, ".agents", "skills");
+}
+
 type EnsureCodexSkillsInjectedOptions = {
   skillsHome?: string;
   skillsEntries?: Array<{ key: string; runtimeName: string; source: string }>;
@@ -154,18 +157,8 @@ export async function ensureCodexSkillsInjected(
   const skillsEntries = allSkillsEntries.filter((entry) => desiredSet.has(entry.key));
   if (skillsEntries.length === 0) return;
 
-  const skillsHome = options.skillsHome ?? path.join(resolveCodexHomeDir(process.env), "skills");
+  const skillsHome = options.skillsHome ?? resolveCodexWorkspaceSkillsDir(process.cwd());
   await fs.mkdir(skillsHome, { recursive: true });
-  const removedSkills = await removeMaintainerOnlySkillSymlinks(
-    skillsHome,
-    skillsEntries.map((entry) => entry.runtimeName),
-  );
-  for (const skillName of removedSkills) {
-    await onLog(
-      "stdout",
-      `[paperclip] Removed maintainer-only Codex skill "${skillName}" from ${skillsHome}\n`,
-    );
-  }
   const linkSkill = options.linkSkill;
   for (const entry of skillsEntries) {
     const target = path.join(skillsHome, entry.runtimeName);
@@ -279,10 +272,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     configuredCodexHome ? null : await prepareWorktreeCodexHome(process.env, onLog, agent.companyId);
   const defaultCodexHome = resolveCodexHomeDir(process.env, agent.companyId);
   const effectiveCodexHome = configuredCodexHome ?? preparedWorktreeCodexHome ?? defaultCodexHome;
+  const codexWorkspaceSkillsDir = resolveCodexWorkspaceSkillsDir(cwd);
   await ensureCodexSkillsInjected(
     onLog,
     {
-      skillsHome: path.join(effectiveCodexHome, "skills"),
+      skillsHome: codexWorkspaceSkillsDir,
       skillsEntries: codexSkillEntries,
       desiredSkillNames,
     },

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

@@ -1,91 +1,82 @@
-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 {
-  buildPersistentSkillSnapshot,
-  ensurePaperclipSkillSymlink,
   readPaperclipRuntimeSkillEntries,
-  readInstalledSkillTargets,
   resolvePaperclipDesiredSkillNames,
 } 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>, companyId?: string) {
-  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, companyId);
-  return path.join(home, "skills");
-}
-
 async function buildCodexSkillSnapshot(
   config: Record<string, unknown>,
-  companyId?: string,
 ): Promise<AdapterSkillSnapshot> {
   const availableEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);
+  const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
   const desiredSkills = resolvePaperclipDesiredSkillNames(config, availableEntries);
-  const skillsHome = resolveCodexSkillsHome(config, companyId);
-  const installed = await readInstalledSkillTargets(skillsHome);
-  return buildPersistentSkillSnapshot({
+  const desiredSet = new Set(desiredSkills);
+  const entries: AdapterSkillEntry[] = availableEntries.map((entry) => ({
+    key: entry.key,
+    runtimeName: entry.runtimeName,
+    desired: desiredSet.has(entry.key),
+    managed: true,
+    state: desiredSet.has(entry.key) ? "configured" : "available",
+    origin: entry.required ? "paperclip_required" : "company_managed",
+    originLabel: entry.required ? "Required by Paperclip" : "Managed by Paperclip",
+    readOnly: false,
+    sourcePath: entry.source,
+    targetPath: null,
+    detail: desiredSet.has(entry.key)
+      ? "Will be linked into the workspace .agents/skills directory on the next run."
+      : null,
+    required: Boolean(entry.required),
+    requiredReason: entry.requiredReason ?? null,
+  }));
+  const warnings: string[] = [];
+
+  for (const desiredSkill of desiredSkills) {
+    if (availableByKey.has(desiredSkill)) continue;
+    warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+    entries.push({
+      key: desiredSkill,
+      runtimeName: null,
+      desired: true,
+      managed: true,
+      state: "missing",
+      origin: "external_unknown",
+      originLabel: "External or unavailable",
+      readOnly: false,
+      sourcePath: null,
+      targetPath: null,
+      detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+    });
+  }
+
+  entries.sort((left, right) => left.key.localeCompare(right.key));
+
+  return {
     adapterType: "codex_local",
-    availableEntries,
+    supported: true,
+    mode: "ephemeral",
     desiredSkills,
-    installed,
-    skillsHome,
-    locationLabel: "$CODEX_HOME/skills",
-    missingDetail: "Configured but not currently linked into the Codex skills home.",
-    externalConflictDetail: "Skill name is occupied by an external installation.",
-    externalDetail: "Installed outside Paperclip management.",
-  });
+    entries,
+    warnings,
+  };
 }
 
 export async function listCodexSkills(ctx: AdapterSkillContext): Promise<AdapterSkillSnapshot> {
-  return buildCodexSkillSnapshot(ctx.config, ctx.companyId);
+  return buildCodexSkillSnapshot(ctx.config);
 }
 
 export async function syncCodexSkills(
   ctx: AdapterSkillContext,
-  desiredSkills: string[],
+  _desiredSkills: string[],
 ): Promise<AdapterSkillSnapshot> {
-  const availableEntries = await readPaperclipRuntimeSkillEntries(ctx.config, __moduleDir);
-  const desiredSet = new Set([
-    ...desiredSkills,
-    ...availableEntries.filter((entry) => entry.required).map((entry) => entry.key),
-  ]);
-  const skillsHome = resolveCodexSkillsHome(ctx.config, ctx.companyId);
-  await fs.mkdir(skillsHome, { recursive: true });
-  const installed = await readInstalledSkillTargets(skillsHome);
-  const availableByRuntimeName = new Map(availableEntries.map((entry) => [entry.runtimeName, entry]));
-
-  for (const available of availableEntries) {
-    if (!desiredSet.has(available.key)) continue;
-    const target = path.join(skillsHome, available.runtimeName);
-    await ensurePaperclipSkillSymlink(available.source, target);
-  }
-
-  for (const [name, installedEntry] of installed.entries()) {
-    const available = availableByRuntimeName.get(name);
-    if (!available) continue;
-    if (desiredSet.has(available.key)) continue;
-    if (installedEntry.targetPath !== available.source) continue;
-    await fs.unlink(path.join(skillsHome, name)).catch(() => {});
-  }
-
-  return buildCodexSkillSnapshot(ctx.config, ctx.companyId);
+  return buildCodexSkillSnapshot(ctx.config);
 }
 
 export function resolveCodexDesiredSkillNames(