fix(hermes): inject task-local Paperclip env into gateway runs

[thedelph]

Thinking Path

• Paperclip manages AI agents and their work.
• The heartbeat service gives each supported adapter a short-lived agent JWT.
• The Hermes Gateway adapter did not declare support for that JWT.
• The adapter also did not send a Paperclip environment in the remote Hermes run body.
• A remote Hermes worker therefore received the task prompt but no authenticated Paperclip access.
• This pull request enables JWT minting and sends a bounded task-local environment.
• The benefit is that a Hermes Gateway worker can read and update its assigned Paperclip task without a long-lived board credential.

Linked Issues or Issue Description

What happened?

The built-in Hermes Gateway adapter set supportsLocalAgentJwt to false. The heartbeat service therefore did not create ctx.authToken. The gateway run body also did not create an environment object. A Hermes worker started by the gateway had no PAPERCLIP_API_URL, PAPERCLIP_API_KEY, or PAPERCLIP_RUN_ID.

Expected behavior

Each Hermes Gateway heartbeat must get a short-lived agent JWT. The created Hermes run must receive the Paperclip URL, JWT, run ID, agent ID, company ID, task ID, and wake reason. The adapter must not forward unrelated environment values from payloadTemplate.

Steps to reproduce

1. Configure an agent with the built-in hermes_gateway adapter.
2. Start an issue heartbeat.
3. Inspect the environment of the created Hermes run.
4. Observe that the Paperclip URL, API key, and run ID are absent on master before this change.

Paperclip version or commit

ee851fc36 on master.

Deployment mode

Self-hosted server.

Agent adapter(s) involved

Hermes.

What Changed

• The Hermes Gateway adapter now declares supportsLocalAgentJwt: true.
• The gateway now builds a task-local Paperclip environment from the heartbeat context.
• The gateway sends the short-lived JWT only in the created Hermes run body.
• The gateway ignores payloadTemplate.environment to prevent credential override and unrelated secret forwarding.
• The gateway redactor now removes the Paperclip JWT from logs, streamed output, summaries, and result metadata.
• The adapter configuration document now describes the runtime and security contract.
• Tests cover capability discovery, exact environment injection, template isolation, and JWT redaction.

Verification

• pnpm --filter @paperclipai/hermes-paperclip-adapter test -- src/gateway/server/execute.test.ts src/index.test.ts (27 tests passed).
• pnpm --filter @paperclipai/hermes-paperclip-adapter typecheck (passed).
• pnpm --filter @paperclipai/server exec vitest run src/__tests__/adapter-registry.test.ts (14 tests passed).
• git diff --check (passed).
• The package lint command could not run because this workspace does not install an eslint executable.

Risks

• A Hermes Gateway endpoint now receives a short-lived Paperclip agent JWT. Operators must protect the gateway transport and endpoint.
• The change intentionally drops any user-defined payloadTemplate.environment. This closes an unsafe override path but can affect a configuration that depended on that undocumented field.
• The JWT remains limited to the agent, company, run, and task scope enforced by Paperclip.

For core feature work, check 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 GPT-5.6-Sol through Codex. The model used reasoning, repository tools, code execution, and test execution. The runtime did not report a context window size.

Checklist

• I have included a thinking path that traces from project context to this change
• I have specified the model used (with version and capability details)
• I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work
• I have searched GitHub for duplicate or related PRs and linked them above
• I have either (a) linked existing issues with Fixes: # / Closes # / Refs # OR (b) described the issue in-PR following the relevant issue template
• I have not referenced internal/instance-local Paperclip issues or links (only public GitHub #NNN / github.com/paperclipai/paperclip URLs)
• My branch name describes the change (e.g. docs/..., fix/...) and contains no internal Paperclip ticket id or instance-derived details
• I have run tests locally and they pass
• I have added or updated tests where applicable
• I have updated relevant documentation to reflect my changes
• I have considered and documented any risks above
• All Paperclip CI gates are green
• Greptile is 5/5 with no open P2s, recommendations, or follow-ups
• I will address all Greptile and reviewer comments before requesting merge

[greptile-apps]

Greptile Summary

The PR enables heartbeat-scoped JWTs for Hermes Gateway runs and injects a bounded Paperclip environment into each remote run.

• Marks the Hermes Gateway adapter as supporting local agent JWTs.
• Builds an adapter-owned environment containing Paperclip run and task context.
• Prevents payload templates from overriding or extending that environment.
• Adds the JWT to output redaction and updates capability and execution tests.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
packages/adapters/hermes/src/gateway/index.ts	Declares heartbeat-scoped JWT support and documents the gateway environment and security contract.
packages/adapters/hermes/src/gateway/server/execute.ts	Constructs the task-local Paperclip environment, excludes template-provided environment values, and redacts the injected JWT.
packages/adapters/hermes/src/gateway/server/execute.test.ts	Verifies exact environment injection, template isolation, and JWT redaction from output and logs.
packages/adapters/hermes/src/index.test.ts	Updates the package-level capability assertion for local agent JWT support.
server/src/tests/adapter-registry.test.ts	Updates registry coverage for the Hermes Gateway JWT capability.
server/src/tests/adapter-routes.test.ts	Updates the public adapter-capability response expectation.

_{Reviews (2): Last reviewed commit: "test(server): update Hermes gateway JWT ..." | Re-trigger Greptile}

[spiffaz]

Companion Hermes runtime support is open at NousResearch/hermes-agent#81976. It accepts this PR’s bounded environment payload, binds it with request-local ContextVars, bridges it only into tool subprocesses, rejects unallowlisted names, and does not mutate global process state.

[spiffaz]

Hermes-side support for the bounded, request-scoped run environment is open at NousResearch/hermes-agent#81976. That PR accepts the environment field used here (plus the explicit runtime_env alias), binds it with context-local state, and bridges it only to tool subprocesses. The two PRs form the complete remote heartbeat credential path.

[spiffaz]

Companion Hermes support is now available in NousResearch/hermes-agent#81976. It accepts the bounded environment payload used here, validates the Paperclip key allowlist, binds values with ContextVar, and exposes them only to tool subprocesses without mutating os.environ. Focused Hermes evidence: 19 API-run tests and 17 local environment bridge tests passed.

[spiffaz]

Security review follow-up is pushed to the companion Hermes receiver at NousResearch/hermes-agent#81976. It now makes an empty scoped request authoritative over ambient PAPERCLIP_* values, excludes those values from reusable shell snapshots, adds run-local exact-value redaction, suppresses token-unsafe SSE deltas, and rejects malformed runtime values. Current focused Hermes verification: 205 passed plus Ruff, py_compile, and git diff checks. Rollout must be receiver-first: deploy Hermes #81976 before enabling this sender because an older gateway can ignore the environment field.