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:
DottaandPaperclip authored and GitHub committed 2026-08-26 09:45:24 -05:00
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;
+3 -2
View File
@@ -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,