mirror of
https://github.com/paperclipai/paperclip
synced 2026-04-25 17:25:15 +02:00
24232078fd
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies > - Adapters are how paperclip hands work off to specific agent runtimes; since #2218, external adapter packages can ship as npm modules loaded via `server/src/adapters/plugin-loader.ts` > - Each `ServerAdapterModule` can declare `sessionManagement` (`supportsSessionResume`, `nativeContextManagement`, `defaultSessionCompaction`) — but the init-time load at `registry.ts:363-369` hard-overwrote it with a hardcoded-registry lookup that has no entries for external types, so modules could not actually set these fields > - The hot-install path at `routes/adapters.ts:179` → `registerServerAdapter` preserves module-provided `sessionManagement`, so externals worked after `POST /api/adapters/install` — *until the next server restart*, when the init-time IIFE wiped it back to `undefined` > - #2218 explicitly deferred this: *"Adapter execution model, heartbeat protocol, and session management are untouched."* This PR is the natural follow-up for session management on the plugin-loader path > - This PR aligns init-time registration with the hot-install path: honor module-provided `sessionManagement` first, fall back to the hardcoded registry when absent (so externals overriding a built-in type still inherit its policy). Extracted as a testable helper with three unit tests > - The benefit is external adapters can declare session-resume capabilities consistently across cold-start and hot-install, without requiring upstream additions to the hardcoded registry for each new plugin ## What Changed - `server/src/adapters/registry.ts`: extracted the merge logic into a new exported helper `resolveExternalAdapterRegistration()` — honors module-provided `sessionManagement` first, falls back to `getAdapterSessionManagement(type)`, else `undefined`. The init-time IIFE calls the helper instead of inlining an overwrite. - `server/src/adapters/registry.ts`: updated the section comment (lines 331–340) to reflect the new semantics and cross-reference the hot-install path's behavior. - `server/src/__tests__/adapter-registry.test.ts`: new `describe("resolveExternalAdapterRegistration")` block with three tests — module-provided value preserved, registry fallback when module omits, `undefined` when neither provides. ## Verification Targeted test run from a clean tree on `fix/external-session-management`: ``` cd server && pnpm exec vitest run src/__tests__/adapter-registry.test.ts # 1 test file, 15 tests passed, 0 failed (12 pre-existing + 3 new) ``` Full server suite via the independent review pass noted under Model Used: **1,156 tests passed, 0 failed**. Typecheck note: `pnpm --filter @paperclipai/server exec tsc --noEmit` surfaces two errors in `src/services/plugin-host-services.ts:1510` (`createInteraction` + implicit-any). Verified by `git stash` + re-run on clean `upstream/master` — they reproduce without this PR's changes. Pre-existing, out of scope. ## Risks - **Low behavioral risk.** Strictly additive: externals that do NOT provide `sessionManagement` continue to receive exactly the same value as before (registry lookup → `undefined` for pure externals, or the builtin's entry for externals overriding a built-in type). Only a new capability is unlocked; no existing behavior changes for existing adapters. - **No breaking change.** `ServerAdapterModule.sessionManagement` was already optional at the type level. Externals that never set it see no difference on either path. - **Consistency verified.** Init-time IIFE now matches the post-`POST /api/adapters/install` behavior — a server restart no longer regresses the field. ## Note This is part of a broader effort to close the parity gap between external and built-in adapters. Once externals reach 1:1 capability coverage with internals, new-adapter contributions can increasingly be steered toward the external-plugin path instead of the core product — a trajectory CONTRIBUTING.md already encourages ("*If the idea fits as an extension, prefer building it with the plugin system*"). ## Model Used - **Provider**: Anthropic - **Model**: Claude Opus 4.7 - **Exact model ID**: `claude-opus-4-7` (1M-context variant: `claude-opus-4-7[1m]`) - **Context window**: 1,000,000 tokens - **Harness**: Claude Code (Anthropic's official CLI), orchestrated by @superbiche as human-in-the-loop. Full file-editing, shell, and `gh` tool use, plus parallel research subagents for fact-finding against paperclip internals (plugin-loader contract, sessionCodec reachability, UI parser surface, Cline CLI JSON schema). - **Independent local review**: Gemini 3.1 Pro (Google) performed a separate verification pass on the committed branch — confirmed the approach & necessity, ran the full workspace build, and executed the complete server test suite (1,156 tests, all passing). Not used for authoring; second-opinion pass only. - **Authoring split**: @superbiche identified the gap (while mapping the external-adapter surface for a downstream adapter build) and shaped the plan — categorising the surface into `works / acceptable / needs-upstream` buckets, directing the surgical-diff approach on a fresh branch from `upstream/master`, and calling the framing ("alignment bug between init-time IIFE and hot-install path" rather than "missing capability"). Opus 4.7 executed the fact-finding, the diff, the tests, and drafted this PR body — all under direct review. ## 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 (convention-aligned bug fix on the external-adapter plugin path introduced by #2218) - [x] I have run tests locally and they pass (15/15 in the touched file; 1,156/1,156 full server suite via the independent Gemini 3.1 Pro review) - [x] I have added tests where applicable (3 new for the extracted helper) - [x] If this change affects the UI, I have included before/after screenshots (no UI touched) - [x] I have updated relevant documentation to reflect my changes (in-file comment reflects new semantics) - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge