## Thinking Path
> - Paperclip orchestrates AI agents through server-side adapters.
> - Some adapters are bundled as built-ins, while external adapter
plugins can provide newer or organization-specific implementations.
> - The adapter registry already supports external plugins overriding a
built-in type while keeping the built-in available as fallback.
> - The hot-install API still rejected built-in adapter types before
registration, so plugin installation did not match registry behavior.
> - That blocked users from installing an external adapter update for a
built-in adapter type such as `hermes_local`.
> - This pull request removes the hot-install conflict guard and keeps
the existing fallback lifecycle intact.
> - The benefit is consistent adapter override behavior across startup
registration, hot install, pause/resume, and removal.
Fixes#7395
## What Changed
- Allows `POST /api/adapters/install` to register an external adapter
whose type matches a built-in adapter.
- Keeps built-in adapters protected from deletion unless there is an
external plugin record for that adapter type.
- Tightens the install route so `requiresRestart` is only reported on a
true reinstall (existing external plugin record), not on a first-time
override of a built-in adapter type.
- Adds route coverage for installing a built-in type override, pausing
back to the built-in implementation, deleting the override, and
restoring the built-in adapter.
## Verification
- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/adapter-routes.test.ts
src/__tests__/adapter-registry.test.ts`
- `pnpm --filter @paperclipai/server typecheck`
- GitHub Actions passed for server tests, typecheck, build, serialized
server suites, e2e, canary dry run, Socket, Snyk, Greptile, and policy
checks on the prior pushed commit before the follow-up review fix.
## Risks
- Low risk: this only changes the hot-install/removal lifecycle for
external plugins targeting a built-in adapter type.
- Built-in adapters remain protected when no external plugin record
exists.
- The existing registry fallback behavior restores the built-in adapter
when an override is paused or removed.
> 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 GPT-5.5 via Hermes Agent for the initial implementation
and verification (terminal/file/GitHub tool use).
- Anthropic Claude Opus 4.7 (claude-opus-4-7) via Paperclip Claude
adapter for the Greptile-feedback follow-up commit (extended-thinking
reasoning, terminal/file/GitHub tool use).
## 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 confirmed
none exist for this hot-install override fix
- [x] I have linked the existing issue with `Fixes #7395`
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] If this change affects the UI, I have included before/after
screenshots
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [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: HenkDz <henkdz@users.noreply.github.com>
Co-authored-by: Devin Foley <devin@devinfoley.com>
Co-authored-by: Paperclip <noreply@paperclip.ing>
Nour Eddine Hamaidi
823c2b115a