fix: improve Hermes adapter reliability on Windows#206
Open
patkaryash wants to merge 1 commit into
Open
Conversation
- Patch hermes-paperclip-adapter@0.2.0 for Paperclip auth and workspace resolution - Add Authorization header guidance and propagate PAPERCLIP_API_KEY from ctx.authToken - Resolve cwd from paperclipWorkspace realizations - Ignore persisted sessions by default for fresh issue conversations - Unwrap structured env values - Only apply tsx loader to TS plugin worker entrypoints to avoid tsx Windows ESM bug
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
This PR improves the reliability of the Hermes adapter and plugin loading on Windows.
The changes ensure Hermes receives the execution context required by Paperclip, authenticates API requests correctly, resolves the correct project workspace, and avoids Windows-specific failures when loading JavaScript plugin workers.
##Thinking Path
-Paperclip executes AI agents through pluggable adapters.
-The Hermes adapter is responsible for translating Paperclip execution context into a Hermes run.
-Several runtime assumptions prevented reliable execution on Windows, including workspace resolution, authentication propagation, and plugin loading.
-These issues caused failed executions, incorrect working directories, and plugin startup failures.
-This PR hardens the adapter and plugin loader without changing the user-facing workflow.
-The result is more reliable Hermes execution across local Windows environments.
##What Changed
-Added a patch for hermes-paperclip-adapter@0.2.0.
-Propagated the Paperclip agent token as PAPERCLIP_API_KEY.
-Updated the adapter prompt to use authenticated Paperclip API requests.
-Improved execution context compatibility by merging runtime context with adapter configuration.
-Resolved working directories using Paperclip workspace realizations instead of relying only on configured paths.
-Normalized structured environment variable values before launching Hermes.
-Started each issue in a fresh Hermes session by default instead of automatically resuming previous sessions.
-Updated the plugin loader so the tsx loader is only applied to TypeScript worker entrypoints. JavaScript workers now execute natively, avoiding Windows ESM loader failures.
-Added the required pnpm patch configuration and lockfile entries for the patched adapter.
##Verification
-Verified Hermes launches using the correct project workspace.
-Verified authenticated Paperclip API requests using the injected agent token.
-Verified JavaScript plugin workers start without the Windows tsx ESM loader failure.
-Verified the adapter patch is applied correctly through pnpm.
-Confirmed the PR contains only the intended Hermes adapter and plugin loader changes.
##Risks
-Low risk.
-The adapter patch targets hermes-paperclip-adapter@0.2.0; future upstream releases may require regenerating the patch.
-The plugin loader change only affects how worker entrypoints are launched and should not affect runtime behavior for existing TypeScript plugins.
##Model Used
-Hermes CLI (Kimi Coding) for implementation assistance.
-ChatGPT GPT-5.5 for design review, change isolation, and PR review.