mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-22 20:29:18 +01:00
fix(adapters): restore Paperclip skill for legacy runners (#12225)
<!-- Write all pull request text in Simplified Technical English (ASD-STE100): short sentences, one instruction per sentence, simple approved vocabulary, and the active voice. --> ## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work. > - Legacy local adapters run agents that use the Paperclip skill for the control-plane workflow. > - PR #7029 removed the required-skill fallback and made runtime skill selection depend only on stored preferences. > - No migration or runtime fallback replaced that behavior for existing agents or non-CEO agents. > - PR #12138 added core skills to new CEOs, and PR #12147 added Claude skill discovery. These changes did not mount the operational skill for all legacy agents. > - This pull request makes the operational skill a legacy adapter runtime invariant. It keeps all other skills configurable. > - The native runner stays unchanged because its protocol supplies the control-plane contract. > - The benefit is that new and existing legacy agents can always operate through Paperclip. ## Linked Issues or Issue Description Refs #7029 Refs #12138 Refs #12147 **What happened?** A skill-capable legacy local agent could start without `paperclipai/paperclip/paperclip`. This happened when the agent had no stored skill preference. An explicit empty preference also removed the skill. The agent then reported that the Paperclip skill was not available. **Expected behavior** Every skill-capable legacy local adapter must mount the Paperclip operational skill when the runtime inventory contains it. Optional skills must remain configurable. The native runner must keep its current protocol-based behavior. **Steps to reproduce** 1. Create a non-CEO `codex_local` agent without `paperclipSkillSync` preferences. 2. Start a legacy heartbeat. 3. Inspect the managed `CODEX_HOME/skills` directory. 4. Observe that the Paperclip skill is absent before this change. **Paperclip version or commit** The problem reproduces on `master` before this pull request. PR #7029 introduced the configured-only selection behavior. **Deployment mode** Local development and self-hosted legacy local adapters. ## What Changed - Added a shared legacy skill resolver that always selects the canonical Paperclip operational skill when it is available. - Applied the resolver to direct adapter execution, ACPX execution, skill snapshots, and persistent skill sync. - Added Hermes skill materialization at sync and run boundaries. - Aligned Cursor, Gemini, and OpenCode execution-time injection with the configured child `HOME`. - Made Hermes stop execution when another installation blocks the required operational skill. - Kept optional skills controlled by `paperclipSkillSync.desiredSkills`. - Kept `paperclip_runner` on the configurable-only resolver. - Added regression coverage for missing preferences, empty preferences, each skill-capable legacy adapter, ACPX, Hermes, and native runner isolation. - Documented the legacy runtime invariant. ## Verification - `pnpm -r typecheck` passed on the pushed commit. - `pnpm build` passed on the pushed commit. - The adapter utility regression suites passed: 236 tests. - The changed server adapter suites passed: 48 tests across 12 files. - The OpenCode adapter suite passed: 8 tests. - The Hermes adapter suite passed: 7 tests. - `git diff --check` passed. - `pnpm test:run` is not clean on this macOS host. The command reported failures in unchanged workspace and filesystem suites. An isolated rerun of `company-skills.test.ts` and `company-skills-service.test.ts` reproduced 11 failures because macOS resolved `/var/...` paths as `/private/var/...`. The changed adapter suites pass independently. ## Risks - This change deliberately makes the operational skill non-removable for skill-capable legacy local adapters. - Existing agents receive the skill on their next list, sync, or run boundary. No database migration is required. - The resolver does not create a skill when the runtime inventory does not contain the canonical entry. - Hermes aborts a run if another installation occupies the required operational skill target. - Hermes removes only an undesired Paperclip-owned symlink that still points to the known Paperclip source. - The native runner does not receive the legacy default. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used OpenAI Codex based on GPT-5. The exact serving model ID and context window were not exposed. The agent used reasoning, tool use, and code execution. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] All Paperclip CI gates are green - [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
1 parent
6524d2b67f
commit
a9d0927fe8
37 files changed
+549
-121
No files matched your search
@@ -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 () => {
|
||||
|
||||
@@ -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",
|
||||
|
||||
@@ -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);
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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-");
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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 },
|
||||
],
|
||||
|
||||
@@ -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;
|
||||
|
||||
|
||||
@@ -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,
|
||||
|
||||
Reference in new issue
Block a user