The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
[codex] Add built-in Hermes adapters (#8543)
Dottafd2f82ac5bba
diff --git a/AGENTS.md b/AGENTS.mdindex 52bc6c0a57..ddefe527d6 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -181,18 +181,19 @@ A change is done when all are true:## 11. Fork-Specific: HenkDz/paperclip-This is a fork of `paperclipai/paperclip` with QoL patches and an **external-only** Hermes adapter story on branch `feat/externalize-hermes-adapter` ([tree](https://github.com/HenkDz/paperclip/tree/feat/externalize-hermes-adapter)).+This is a fork of `paperclipai/paperclip` with QoL patches and a **built-in** Hermes adapter story on branch `feat/externalize-hermes-adapter` ([tree](https://github.com/HenkDz/paperclip/tree/feat/externalize-hermes-adapter)).### Branch Strategy-- `feat/externalize-hermes-adapter` → core has **no** `hermes-paperclip-adapter` dependency and **no** built-in `hermes_local` registration. Install Hermes via the Adapter Plugin manager (`@henkey/hermes-paperclip-adapter` or a `file:` path).-- Older fork branches may still document built-in Hermes; treat this file as authoritative for the externalize branch.+- `feat/externalize-hermes-adapter` now ships `hermes_local` and `hermes_gateway` as built-in core adapters.+- Older fork branches may still document plugin-only Hermes; treat this file as authoritative for the current branch.-### Hermes (plugin only)+### Hermes (built-in)-- Register through **Board → Adapter manager** (same as Droid). Type remains `hermes_local` once the package is loaded.-- UI uses generic **config-schema** + **ui-parser.js** from the package — no Hermes imports in `server/` or `ui/` source.-- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` for local dev of the adapter repo.+- `hermes_local` is available without Adapter manager installation and runs the local Hermes CLI.+- `hermes_gateway` is available without Adapter manager installation and calls an already-running Hermes API server.+- Operators may still install external Hermes packages through Adapter manager to override/shadow the built-ins.+- Optional: `file:` entry in `~/.paperclip/adapter-plugins.json` remains useful for local development of override packages.### Local Dev@@ -217,5 +218,5 @@ PR #2218 (`feat/external-adapter-phase1`) adds external adapter support. See roo- Adapters can be loaded as external plugins via `~/.paperclip/adapter-plugins.json`- The plugin-loader should have ZERO hardcoded adapter imports — pure dynamic loading- `createServerAdapter()` must include ALL optional fields (especially `detectModel`)-- Built-in UI adapters can shadow external plugin parsers — remove built-in when fully externalizing-- Reference external adapters: Hermes (`@henkey/hermes-paperclip-adapter` or `file:`) and Droid (npm)+- Built-in UI adapters can shadow external plugin parsers; external override pause/resume should restore the built-in parser.+- Reference external adapters: Droid (npm); Hermes can also be tested as an override package.diff --git a/Dockerfile b/Dockerfileindex cc503d98b6..a6631b71f5 100644--- a/Dockerfile+++ b/Dockerfile@@ -31,6 +31,8 @@ COPY packages/adapters/cursor-cloud/package.json packages/adapters/cursor-cloud/COPY packages/adapters/cursor-local/package.json packages/adapters/cursor-local/COPY packages/adapters/gemini-local/package.json packages/adapters/gemini-local/COPY packages/adapters/grok-local/package.json packages/adapters/grok-local/+COPY packages/adapters/hermes/package.json packages/adapters/hermes/+COPY packages/adapters/hermes-gateway/package.json packages/adapters/hermes-gateway/COPY packages/adapters/openclaw-gateway/package.json packages/adapters/openclaw-gateway/COPY packages/adapters/opencode-local/package.json packages/adapters/opencode-local/COPY packages/adapters/pi-local/package.json packages/adapters/pi-local/diff --git a/cli/esbuild.config.mjs b/cli/esbuild.config.mjsindex 7976b7c9cd..c92ea4f06f 100644--- a/cli/esbuild.config.mjs+++ b/cli/esbuild.config.mjs@@ -21,6 +21,8 @@ const workspacePaths = ["packages/adapter-utils","packages/adapters/claude-local","packages/adapters/codex-local",+ "packages/adapters/hermes-gateway",+ "packages/adapters/hermes","packages/adapters/openclaw-gateway",];diff --git a/cli/package.json b/cli/package.jsonindex ed894750eb..256291c2ef 100644--- a/cli/package.json+++ b/cli/package.json@@ -51,6 +51,7 @@"@paperclipai/db": "workspace:*","@paperclipai/server": "workspace:*","@paperclipai/shared": "workspace:*",+ "@paperclipai/hermes-paperclip-adapter": "workspace:*","drizzle-orm": "0.45.2","dotenv": "^17.0.1","commander": "^13.1.0",diff --git a/cli/src/__tests__/token.test.ts b/cli/src/__tests__/token.test.tsindex 02d53fe1e7..0242427d44 100644--- a/cli/src/__tests__/token.test.ts+++ b/cli/src/__tests__/token.test.ts@@ -70,7 +70,10 @@ describe("token commands", () => {expect(fetchMock.mock.calls[0]?.[0]).toBe(`http://localhost:3100/api/agents/worker?companyId=${COMPANY_ID}`);expect(fetchMock.mock.calls[1]?.[0]).toBe(`http://localhost:3100/api/agents/${AGENT_ID}/keys`);- expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).toEqual({ name: "external-worker" });+ expect(JSON.parse(String(fetchMock.mock.calls[1]?.[1]?.body))).toEqual({+ name: "external-worker",+ scope: { kind: "standard" },+ });expect(JSON.parse(String(log.mock.calls[0]?.[0]))).toMatchObject({agentId: AGENT_ID,companyId: COMPANY_ID,diff --git a/cli/src/adapters/registry.ts b/cli/src/adapters/registry.tsindex 31dfe0d0af..260a45d6a3 100644--- a/cli/src/adapters/registry.ts+++ b/cli/src/adapters/registry.ts@@ -6,6 +6,8 @@ import { printCursorStreamEvent } from "@paperclipai/adapter-cursor-local/cli";import { printCursorCloudEvent } from "@paperclipai/adapter-cursor-cloud/cli";import { printGeminiStreamEvent } from "@paperclipai/adapter-gemini-local/cli";import { printGrokStreamEvent } from "@paperclipai/adapter-grok-local/cli";+import { formatStdoutEvent as printHermesGatewayStreamEvent } from "@paperclipai/hermes-paperclip-adapter/gateway/cli";+import { printHermesStreamEvent } from "@paperclipai/hermes-paperclip-adapter/cli";import { printOpenCodeStreamEvent } from "@paperclipai/adapter-opencode-local/cli";import { printPiStreamEvent } from "@paperclipai/adapter-pi-local/cli";import { printOpenClawGatewayStreamEvent } from "@paperclipai/adapter-openclaw-gateway/cli";@@ -57,6 +59,16 @@ const grokLocalCLIAdapter: CLIAdapterModule = {formatStdoutEvent: printGrokStreamEvent,};+const hermesGatewayCLIAdapter: CLIAdapterModule = {+ type: "hermes_gateway",+ formatStdoutEvent: printHermesGatewayStreamEvent,+};++const hermesLocalCLIAdapter: CLIAdapterModule = {+ type: "hermes_local",+ formatStdoutEvent: printHermesStreamEvent,+};+const openclawGatewayCLIAdapter: CLIAdapterModule = {type: "openclaw_gateway",formatStdoutEvent: printOpenClawGatewayStreamEvent,@@ -73,6 +85,8 @@ const adaptersByType = new Map<string, CLIAdapterModule>(cursorCloudCLIAdapter,geminiLocalCLIAdapter,grokLocalCLIAdapter,+ hermesGatewayCLIAdapter,+ hermesLocalCLIAdapter,openclawGatewayCLIAdapter,processCLIAdapter,httpCLIAdapter,diff --git a/doc/CLI.md b/doc/CLI.mdindex 2b4bfe6fc5..fd190a0e80 100644--- a/doc/CLI.md+++ b/doc/CLI.md@@ -688,6 +688,13 @@ pnpm paperclipai llm agent-configuration:adapter <adapter-type>pnpm paperclipai llm agent-icons```+Hermes gateway uses the generic invite/join commands above rather than+`openclaw invite-prompt`. Create an agent invite, read+`invite onboarding:text`, submit a join request with+`adapterType: "hermes_gateway"` and `agentDefaultsPayload.apiBaseUrl` /+`agentDefaultsPayload.apiKey`, then approve and claim the key with the `join`+commands. See [HERMES_GATEWAY_ONBOARDING.md](./HERMES_GATEWAY_ONBOARDING.md).+## Adapter, Asset, And Skill Commands```shdiff --git a/doc/DEVELOPING.md b/doc/DEVELOPING.mdindex f15c244098..aa47541b0a 100644--- a/doc/DEVELOPING.md+++ b/doc/DEVELOPING.md@@ -710,6 +710,13 @@ The board UI generates agent onboarding prompts from the add-agent modal (`+` in- `GET /api/skills/index` lists available skill documents.- `GET /api/skills/paperclip` returns the Paperclip heartbeat skill markdown.+Hermes gateway agents use this same generic agent invite flow with+`adapterType=hermes_gateway` and `agentDefaultsPayload.apiBaseUrl` /+`agentDefaultsPayload.apiKey`. See+[HERMES_GATEWAY_ONBOARDING.md](./HERMES_GATEWAY_ONBOARDING.md) for the full+operator path, including Hermes credentials, invite approval, key claim, and+fresh-state Docker smoke setup.+## OpenClaw Join Smoke TestRun the end-to-end OpenClaw join smoke harness:diff --git a/doc/HERMES_GATEWAY_ONBOARDING.md b/doc/HERMES_GATEWAY_ONBOARDING.mdnew file mode 100644index 0000000000..58b9dfc5b0--- /dev/null+++ b/doc/HERMES_GATEWAY_ONBOARDING.md@@ -0,0 +1,193 @@+# Hermes Gateway Onboarding++Use this guide when a Hermes runtime should join Paperclip as an external+`hermes_gateway` employee. This mirrors the OpenClaw gateway invite path, but+Hermes uses the generic agent invite/onboarding flow instead of the+OpenClaw-specific invite prompt endpoint.++## Choose The Adapter++Paperclip ships both Hermes adapters as built-ins:++- `hermes_local` runs the local `hermes` CLI as a child process on the+ Paperclip host.+- `hermes_gateway` calls an already-running Hermes API server over HTTP/SSE.++No Adapter manager installation is required for normal use. Adapter manager is+only needed when you intentionally install an external+`@paperclipai/hermes-paperclip-adapter` package to override or shadow a built-in+adapter while developing the Hermes package. If the external override is paused+or removed, Paperclip restores the built-in `hermes_local` / `hermes_gateway`+adapter.++## Required Credentials++Keep these credentials distinct:++- Hermes inference provider key: set at least one provider key for Hermes, such+ as `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`,+ `GEMINI_API_KEY`, `GOOGLE_API_KEY`, or `MISTRAL_API_KEY`.+- Hermes gateway key: set `API_SERVER_KEY` before starting Hermes. Paperclip+ stores the same value as `agentDefaultsPayload.apiKey` so it can call Hermes.+- Paperclip agent key: created after the board approves the join request and+ claimed once by the Hermes agent. Hermes uses this key as+ `PAPERCLIP_API_KEY` when it calls Paperclip.++Do not reuse the Hermes gateway key as the Paperclip agent key. The Hermes+gateway key authenticates Paperclip-to-Hermes traffic; the claimed Paperclip key+authenticates Hermes-to-Paperclip traffic.++## Start Hermes Gateway++Install and configure Hermes first:++```sh+pip install hermes-agent+export OPENROUTER_API_KEY='<provider-key>'+export API_SERVER_KEY='<random-gateway-key>'+API_SERVER_ENABLED=true hermes gateway run --replace --accept-hooks+```++The default Hermes API server port is `8642`. For local loopback testing,+Paperclip can usually store `http://127.0.0.1:8642` as the gateway URL. For+Docker, LAN, tailnet, or reverse-proxy setups, use a URL reachable by the+Paperclip server process.++Plain HTTP is accepted for loopback. Non-loopback HTTP is denied by default in+the join flow; use HTTPS for real remote gateways. For private local+development only, the join payload can set+`dangerouslyAllowInsecureRemoteHttp: true`, and the smoke scripts expose the+same escape hatch as `HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1`.++## Invite From Paperclip++In the board UI:++1. Open the target company.+2. Use the add-agent button in the agent sidebar.+3. Generate an agent onboarding prompt/invite.+4. Give the generated onboarding text to the Hermes runtime.++The UI prompt points Hermes at the same machine-readable onboarding endpoints:++- `GET /api/invites/:token`+- `GET /api/invites/:token/onboarding`+- `GET /api/invites/:token/onboarding.txt`+- `GET /api/skills/index`+- `GET /api/skills/paperclip`++For CLI-driven setup, create and inspect the invite directly:++```sh+pnpm paperclipai invite create --company-id <company-id> --payload-json '{"requestType":"agent"}'+pnpm paperclipai invite show <token>+pnpm paperclipai invite onboarding:text <token>+```++Hermes should submit a join request with `requestType: "agent"` and+`adapterType: "hermes_gateway"`:++```json+{+ "requestType": "agent",+ "agentName": "Hermes Gateway Engineer",+ "adapterType": "hermes_gateway",+ "capabilities": "Hermes gateway agent with code, browser, web, and file tools.",+ "agentDefaultsPayload": {+ "apiBaseUrl": "http://127.0.0.1:8642",+ "apiKey": "<same-value-as-API_SERVER_KEY>",+ "paperclipApiUrl": "http://127.0.0.1:3100",+ "sessionKeyStrategy": "issue"+ }+}+```++Important URL roles:++- `agentDefaultsPayload.apiBaseUrl` is the Hermes gateway URL that Paperclip+ calls.+- `agentDefaultsPayload.paperclipApiUrl` is the Paperclip base URL that Hermes+ can call after approval and key claim.+- `PAPERCLIP_API_URL` / `PAPERCLIP_API_KEY` are injected runtime values for+ Hermes-originated Paperclip API calls after the agent is approved.++## Approve And Claim++After Hermes submits the join request:++1. In Paperclip, review the pending agent join request.+2. Approve it from the board UI, or use:++ ```sh+ pnpm paperclipai join list --company-id <company-id> --status pending_approval+ pnpm paperclipai join approve <request-id> --company-id <company-id>+ ```++3. Hermes claims the one-time agent API key:++ ```sh+ pnpm paperclipai join claim-key <request-id> --claim-secret <secret>+ ```++4. Store the claimed Paperclip key in Hermes runtime state or secrets. The claim+ secret and claimed key are sensitive and should not be pasted into issue+ comments, logs, or prompt text.++Once the key is claimed, create an issue assigned to the new Hermes gateway+agent and wake it through the normal Paperclip heartbeat path.++## Local Fresh-State Smoke++For a fresh Docker-backed Hermes gateway and end-to-end Paperclip join/run+verification, use:++```sh+PAPERCLIP_API_URL=http://127.0.0.1:3100 \+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \+pnpm smoke:hermes-gateway-e2e+```++The E2E smoke:++- builds a fresh Hermes gateway container+- seeds a minimal non-secret Hermes model config+- passes provider keys from the host environment without printing them+- verifies Hermes `/health`, `/v1/capabilities`, `/v1/runs`, SSE, and stop+- creates and approves a Paperclip agent-only invite+- joins as `hermes_gateway`+- wakes the agent on a smoke issue+- removes Paperclip and Docker test state on success++If a Hermes gateway is already running and you only need to validate the invite+and stored adapter config, use the join-only helper:++```sh+API_SERVER_ENABLED=true API_SERVER_KEY='<gateway-key>' hermes gateway run --replace --accept-hooks++PAPERCLIP_API_URL=http://127.0.0.1:3100 \+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \+HERMES_GATEWAY_API_BASE_URL=http://127.0.0.1:8642 \+HERMES_GATEWAY_API_KEY='<gateway-key>' \+pnpm smoke:hermes-gateway-join+```++See [HERMES_GATEWAY_SMOKE.md](./HERMES_GATEWAY_SMOKE.md) for Docker Desktop,+Linux, same-network Docker, LAN/private-network, and reverse-proxy/TLS examples.++## Install Entry Points++Use these entry points depending on who is driving setup:++- Board UI: add-agent button in the agent sidebar, then generate the agent+ onboarding prompt.+- Invite API: `GET /api/invites/:token/onboarding.txt` for the generated+ llm.txt-style setup instructions.+- CLI invite flow: `pnpm paperclipai invite create`, `invite show`,+ `invite onboarding:text`, `join approve`, and `join claim-key`.+- Smoke helpers: `pnpm smoke:hermes-gateway-e2e` for fresh-state Docker+ verification and `pnpm smoke:hermes-gateway-join` for an already-running+ gateway.+- Adapter development override: Adapter manager can install+ `@paperclipai/hermes-paperclip-adapter` as an external override, but normal+ operators should use the built-in `hermes_local` and `hermes_gateway`+ adapters.diff --git a/doc/HERMES_GATEWAY_SMOKE.md b/doc/HERMES_GATEWAY_SMOKE.mdnew file mode 100644index 0000000000..a85026f241--- /dev/null+++ b/doc/HERMES_GATEWAY_SMOKE.md@@ -0,0 +1,168 @@+# Hermes Gateway Smoke++This smoke validates the built-in `hermes_gateway` adapter against a fresh+Hermes gateway. Keep real Hermes execution manual/local: the CI-safe checks only+lint shell syntax and focused helper behavior.++For the operator-facing install and invite flow, see+[HERMES_GATEWAY_ONBOARDING.md](./HERMES_GATEWAY_ONBOARDING.md). This smoke guide+focuses on verification commands and network modes.++## CI-safe validation++Run these from the repo root:++```sh+bash -n scripts/smoke/hermes-gateway-join.sh scripts/smoke/hermes-gateway-e2e.sh+pnpm test:hermes-gateway-smoke+```++`pnpm test:hermes-gateway-smoke` does not start Docker, Hermes, or Paperclip. It+checks script help output, shell syntax, redaction helpers, URL slash handling,+and the non-loopback HTTP guard.++## Secrets and cleanup++- Set the Hermes gateway key with `HERMES_GATEWAY_API_KEY` or `API_SERVER_KEY`.+ The scripts print only `sha256=<prefix>` and length for secret identifiers.+- Set at least one Hermes inference provider key on the host before running the+ Docker E2E smoke. The script passes through set values for+ `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`,+ `GOOGLE_API_KEY`, and `MISTRAL_API_KEY`, and logs only the provider env var+ names.+- To pin the fresh Hermes container to a known non-secret model config, set+ `HERMES_SMOKE_MODEL_PROVIDER`, `HERMES_SMOKE_MODEL_DEFAULT`, and optionally+ `HERMES_SMOKE_MODEL_BASE_URL`. For example, OpenRouter GLM:++ ```sh+ HERMES_SMOKE_MODEL_PROVIDER=openrouter \+ HERMES_SMOKE_MODEL_DEFAULT=z-ai/glm-5.2 \+ HERMES_SMOKE_MODEL_BASE_URL=https://openrouter.ai/api/v1 \+ pnpm smoke:hermes-gateway-e2e+ ```++ This writes only `model`, `providers: {}`, and+ `command_allowlist: [execute_code]` into the temporary Hermes home. Provider+ keys still come from environment variables and are redacted from diagnostics.+- The E2E helper always seeds `command_allowlist: [execute_code]` in the fresh+ Hermes config so non-interactive gateway/API runs do not wait for a manual+ execute-code approval prompt. Do not copy a host `~/.hermes` directory into+ the container to solve approval or provider setup.+- Board/operator auth is required through `PAPERCLIP_AUTH_HEADER`,+ `PAPERCLIP_COOKIE`, or a board-capable `PAPERCLIP_API_KEY`.+- Diagnostic files are redacted before they are written, except the join output+ file intentionally contains the claimed Paperclip agent key and is written+ `chmod 600`.+- Successful runs remove the smoke issue, smoke agent, join request, Docker+ container, and per-run local state.+- Set `HERMES_SMOKE_KEEP=1` to preserve diagnostics, state, and the container.+ Failed runs automatically preserve them and print the retained paths.++## URL model++The smoke has three URLs because different processes need different routes:++- `PAPERCLIP_API_URL`: Paperclip URL used by the operator shell.+- `PAPERCLIP_API_URL_FOR_HERMES`: Paperclip URL used from inside the Hermes+ container or remote Hermes host.+- `HERMES_GATEWAY_API_BASE_URL`: Hermes gateway URL stored on the Paperclip+ adapter, reachable by the Paperclip server.+- `HERMES_GATEWAY_PROBE_URL`: Hermes gateway URL used by the operator shell for+ direct `/health`, `/v1/capabilities`, `/v1/runs`, and SSE checks.++Loopback HTTP gateway URLs are allowed. Non-loopback HTTP gateway URLs require+`HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1` and should only be used on local/private+development networks. Use HTTPS for real remote gateways.++## Docker Desktop or Linux host Paperclip++Use this when Paperclip runs on the host at `127.0.0.1:3100` and Docker can+reach the host through `host.docker.internal`.++```sh+PAPERCLIP_API_URL=http://127.0.0.1:3100 \+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \+pnpm smoke:hermes-gateway-e2e+```++Linux uses `--add-host=host.docker.internal:host-gateway` by default through+`HERMES_DOCKER_ADD_HOST=1`. If your Docker setup already provides+`host.docker.internal`, the same command works.++## Same Docker network as Paperclip++Use this when Paperclip is a container on a Docker network and the Hermes smoke+container should be reachable by container DNS. The operator shell still probes+the host-published loopback port.++```sh+PAPERCLIP_API_URL=http://127.0.0.1:3100 \+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \+HERMES_CONTAINER_NAME=paperclip-hermes-gateway-smoke \+HERMES_SMOKE_NETWORK=paperclip_default \+HERMES_DOCKER_ADD_HOST=0 \+HERMES_GATEWAY_API_BASE_URL=http://paperclip-hermes-gateway-smoke:8642 \+HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642 \+PAPERCLIP_API_URL_FOR_HERMES=http://paperclip:3100 \+HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 \+pnpm smoke:hermes-gateway-e2e+```++Change `paperclip_default` and `paperclip` to your Compose network and service+name. The unsafe HTTP flag is required because Paperclip stores a non-loopback+`http://` gateway URL for private Docker DNS.++## LAN or private-network Paperclip++Use this when Paperclip is exposed on a private IP or tailnet address and the+Hermes container can reach that address.++```sh+PAPERCLIP_API_URL=http://192.168.1.20:3100 \+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \+PAPERCLIP_API_URL_FOR_HERMES=http://192.168.1.20:3100 \+HERMES_GATEWAY_API_BASE_URL=http://192.168.1.20:8642 \+HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642 \+HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 \+pnpm smoke:hermes-gateway-e2e+```++Only use this on a trusted private network. For anything beyond local/private+development, put the Hermes gateway behind TLS and use the reverse-proxy mode.++## Reverse proxy / TLS++Use this when Paperclip should talk to Hermes through a TLS hostname. The smoke+container still publishes a local port, and your reverse proxy forwards the TLS+hostname to that port.++```sh+PAPERCLIP_API_URL=https://paperclip.example.com \+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \+PAPERCLIP_API_URL_FOR_HERMES=https://paperclip.example.com \+HERMES_GATEWAY_API_BASE_URL=https://hermes-gateway.example.com \+HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642 \+pnpm smoke:hermes-gateway-e2e+```++No unsafe HTTP escape hatch is needed because the adapter URL is HTTPS.++## Join-only validation++If a Hermes gateway is already running, use the join helper without building or+starting a Docker container:++```sh+API_SERVER_ENABLED=true API_SERVER_KEY='<gateway-key>' hermes gateway run --replace --accept-hooks++PAPERCLIP_API_URL=http://127.0.0.1:3100 \+PAPERCLIP_AUTH_HEADER='Bearer <board-token>' \+HERMES_GATEWAY_API_BASE_URL=http://127.0.0.1:8642 \+HERMES_GATEWAY_API_KEY='<gateway-key>' \+pnpm smoke:hermes-gateway-join+```++For non-loopback private HTTP join-only runs, set+`HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1`. For Docker DNS or reverse-proxy setups,+set `HERMES_GATEWAY_PROBE_URL` to the URL reachable from the operator shell and+`HERMES_GATEWAY_API_BASE_URL` to the URL Paperclip should store on the adapter.diff --git a/doc/PUBLISHING.md b/doc/PUBLISHING.mdindex c430d3473a..11582e9718 100644--- a/doc/PUBLISHING.md+++ b/doc/PUBLISHING.md@@ -209,8 +209,12 @@ The helper script:- checks that the package does not already exist on npm- builds the target package unless `--skip-build` is passed-- runs `npm pack --dry-run` in the package directory-- only runs the real `npm publish --access public` when `--publish --otp <code>` is provided+- runs `pnpm publish <package-dir> --dry-run --no-git-checks --access public` from the repo root+- only runs the real `pnpm publish <package-dir> --no-git-checks --access public` when `--publish --otp <code>` is provided++The helper intentionally uses `pnpm publish` instead of `npm publish` so workspace+dependencies and `publishConfig` export fields are normalized before the package+is sent to the registry.For the real `--publish` step, the maintainer machine must already be authenticated to npm.If `npm whoami` returns `401`, first run `npm logout --registry=https://registry.npmjs.org/` to clear any stale local auth, then run `npm login` or `npm adduser` locally as an npm org member, and finally rerun the helper.diff --git a/doc/SPEC-implementation.md b/doc/SPEC-implementation.mdindex e3246ed6da..44ff0bb037 100644--- a/doc/SPEC-implementation.md+++ b/doc/SPEC-implementation.md@@ -153,7 +153,7 @@ Invariant: every business record belongs to exactly one company.- `status` enum: `active | paused | idle | running | error | pending_approval | terminated`- `reports_to` uuid fk `agents.id` null- `capabilities` text null-- `adapter_type` text; built-ins include `process`, `http`, `claude_local`, `codex_local`, `gemini_local`, `opencode_local`, `pi_local`, `cursor`, and `openclaw_gateway`+- `adapter_type` text; built-ins include `process`, `http`, `claude_local`, `codex_local`, `gemini_local`, `opencode_local`, `pi_local`, `cursor`, `hermes_local`, `hermes_gateway`, and `openclaw_gateway`- `adapter_config` jsonb not null- `runtime_config` jsonb not null default `{}`; may include Paperclip runtime policy such as `modelProfiles.cheap.adapterConfig` for an optional low-cost model lane that does not change the primary adapter config- `default_environment_id` uuid fk `environments.id` nulldiff --git a/docker/hermes-gateway-smoke/Dockerfile b/docker/hermes-gateway-smoke/Dockerfilenew file mode 100644index 0000000000..5939c7df6e--- /dev/null+++ b/docker/hermes-gateway-smoke/Dockerfile@@ -0,0 +1,52 @@+# syntax=docker/dockerfile:1.6+ARG HERMES_VERSION=0.17.0+FROM node:22-bookworm-slim++ARG HERMES_VERSION++ENV DEBIAN_FRONTEND=noninteractive++RUN apt-get update \+ && apt-get install -y --no-install-recommends \+ bash \+ ca-certificates \+ curl \+ git \+ jq \+ python3 \+ python3-pip \+ tini \+ && rm -rf /var/lib/apt/lists/*++# The npm package is a pinned bridge that exposes the `hermes` binary. Install+# the matching Python package globally first so the non-root runtime user can+# import the upstream Hermes modules at container start.+RUN python3 -m pip install --break-system-packages --no-cache-dir "hermes-agent[anthropic]==${HERMES_VERSION}" "aiohttp==3.13.4" \+ && rm -f /usr/local/bin/hermes /usr/local/bin/hermes-agent \+ && npm install -g --ignore-scripts "hermes-agent@${HERMES_VERSION}" \+ && python3 -c "import hermes_cli.main" \+ && command -v hermes >/dev/null++RUN useradd --create-home --shell /bin/bash --uid 10001 hermes \+ && mkdir -p /home/hermes/.hermes /home/hermes/workspace \+ && chown -R hermes:hermes /home/hermes++COPY entrypoint.sh /usr/local/bin/hermes-gateway-entrypoint+RUN chmod 0755 /usr/local/bin/hermes-gateway-entrypoint++USER hermes+WORKDIR /home/hermes/workspace++ENV HOME=/home/hermes \+ HERMES_HOME=/home/hermes/.hermes \+ XDG_CONFIG_HOME=/home/hermes/.config \+ XDG_CACHE_HOME=/home/hermes/.cache \+ XDG_DATA_HOME=/home/hermes/.local/share \+ API_SERVER_ENABLED=true \+ API_SERVER_HOST=0.0.0.0 \+ API_SERVER_PORT=8642 \+ NO_COLOR=1++EXPOSE 8642++ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/hermes-gateway-entrypoint"]diff --git a/docker/hermes-gateway-smoke/entrypoint.sh b/docker/hermes-gateway-smoke/entrypoint.shnew file mode 100755index 0000000000..a1496afa8c--- /dev/null+++ b/docker/hermes-gateway-smoke/entrypoint.sh@@ -0,0 +1,56 @@+#!/usr/bin/env bash+set -euo pipefail++log() {+ echo "[hermes-gateway-smoke] $*"+}++hash_prefix() {+ local value="$1"+ if command -v sha256sum >/dev/null 2>&1; then+ printf "%s" "$value" | sha256sum | awk '{print substr($1,1,12)}'+ elif command -v shasum >/dev/null 2>&1; then+ printf "%s" "$value" | shasum -a 256 | awk '{print substr($1,1,12)}'+ else+ printf "unavailable"+ fi+}++generate_key() {+ node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))'+}++export HOME="${HOME:-/home/hermes}"+export HERMES_HOME="${HERMES_HOME:-${HOME}/.hermes}"+export XDG_CONFIG_HOME="${XDG_CONFIG_HOME:-${HOME}/.config}"+export XDG_CACHE_HOME="${XDG_CACHE_HOME:-${HOME}/.cache}"+export XDG_DATA_HOME="${XDG_DATA_HOME:-${HOME}/.local/share}"+export API_SERVER_ENABLED="${API_SERVER_ENABLED:-true}"+export API_SERVER_HOST="${API_SERVER_HOST:-0.0.0.0}"+export API_SERVER_PORT="${API_SERVER_PORT:-8642}"+export NO_COLOR="${NO_COLOR:-1}"++if [[ "${API_SERVER_ENABLED}" != "true" ]]; then+ log "forcing API_SERVER_ENABLED=true for gateway smoke"+ export API_SERVER_ENABLED=true+fi++if [[ -z "${API_SERVER_KEY:-}" ]]; then+ API_SERVER_KEY="$(generate_key)"+ export API_SERVER_KEY+ log "generated API_SERVER_KEY sha256=$(hash_prefix "$API_SERVER_KEY") len=${#API_SERVER_KEY}"+else+ log "using provided API_SERVER_KEY sha256=$(hash_prefix "$API_SERVER_KEY") len=${#API_SERVER_KEY}"+fi++mkdir -p "$HERMES_HOME" "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME" "$XDG_DATA_HOME" "$HOME/workspace"+chmod 0700 "$HERMES_HOME" "$XDG_CONFIG_HOME" "$XDG_CACHE_HOME" "$XDG_DATA_HOME" || true++log "HOME=${HOME}"+log "HERMES_HOME=${HERMES_HOME}"+log "workspace=$(pwd)"+log "API_SERVER_HOST=${API_SERVER_HOST}"+log "API_SERVER_PORT=${API_SERVER_PORT}"+log "state listing hash=$(find "$HERMES_HOME" -maxdepth 2 -type f -print 2>/dev/null | sort | sha256sum | awk '{print substr($1,1,12)}')"++exec hermes gateway run --replace --accept-hooks "$@"diff --git a/docs/adapters/external-adapters.md b/docs/adapters/external-adapters.mdindex 3c814fc9ab..522679f667 100644--- a/docs/adapters/external-adapters.md+++ b/docs/adapters/external-adapters.md@@ -15,6 +15,22 @@ Paperclip supports external adapter plugins that can be installed from npm packa| Distribution | Ships with Paperclip | Published to npm or linked via `file:` || Updates | Requires Paperclip release | Independent versioning |+### Built-in Hermes compatibility note++Hermes is built in with two stable adapter type keys:++- `hermes_local` starts the local Hermes CLI from+ `@paperclipai/hermes-paperclip-adapter`.+- `hermes_gateway` calls an already-running Hermes API server through+ `@paperclipai/hermes-paperclip-adapter/gateway`.++The legacy `@paperclipai/adapter-hermes-gateway` package is a deprecated+compatibility shim for one release. It preserves the old gateway exports while+forwarding to the unified Hermes package. New external override packages should+depend on or link `@paperclipai/hermes-paperclip-adapter` and declare the type+they override (`hermes_local` or `hermes_gateway`); the type keys did not+change.+## Quick Start### Minimal Package Structurediff --git a/docs/adapters/overview.md b/docs/adapters/overview.mdindex dfb4b21fb3..a2f62b54bb 100644--- a/docs/adapters/overview.md+++ b/docs/adapters/overview.md@@ -24,11 +24,25 @@ When a heartbeat fires, Paperclip:| OpenCode Local | `opencode_local` | Runs OpenCode CLI locally (multi-provider `provider/model`) || Cursor | `cursor` | Runs Cursor in background mode || Pi Local | `pi_local` | Runs an embedded Pi agent locally |-| Hermes Local | `hermes_local` | Runs Hermes CLI locally (`hermes-paperclip-adapter`) |+| Hermes Local | `hermes_local` | Runs the local Hermes CLI through `@paperclipai/hermes-paperclip-adapter` |+| Hermes Gateway | `hermes_gateway` | Calls an already-running Hermes API server through `@paperclipai/hermes-paperclip-adapter/gateway` || OpenClaw Gateway | `openclaw_gateway` | Connects to an OpenClaw gateway endpoint || [Process](/adapters/process) | `process` | Executes arbitrary shell commands || [HTTP](/adapters/http) | `http` | Sends webhooks to external agents |+### Hermes local vs gateway++Use `hermes_local` when Paperclip should start the local `hermes` CLI on the+same host for each heartbeat. Use `hermes_gateway` when Hermes is already+running as an HTTP/SSE API server and Paperclip should call that server instead+of spawning a process. Both type keys are stable built-ins.++The unified Hermes package owns both built-in adapters. The older+`@paperclipai/adapter-hermes-gateway` package remains only as a deprecated+compatibility shim that re-exports the gateway entrypoints for one release.+New plugin overrides should target `@paperclipai/hermes-paperclip-adapter` and+set the desired type key (`hermes_local` or `hermes_gateway`).+### External (plugin) adaptersThese adapters ship as standalone npm packages and are installed via the plugin system:@@ -79,8 +93,9 @@ my-adapter/## Choosing an Adapter- **Need a coding agent?** Use `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, or install `droid_local` as an external plugin+- **Need Hermes on another host or already running as a service?** Use `hermes_gateway`- **Need to run a script or command?** Use `process`-- **Need to call an external service?** Use `http`+- **Need to call a custom external service?** Use `http`- **Need something custom?** [Create your own adapter](/adapters/creating-an-adapter) or [build an external adapter plugin](/adapters/external-adapters)## UI Parser Contractdiff --git a/docs/agents-runtime.md b/docs/agents-runtime.mdindex 81bbda7ca1..252fa3d0a2 100644--- a/docs/agents-runtime.md+++ b/docs/agents-runtime.md@@ -39,7 +39,8 @@ Built-in adapters:- `opencode_local`: runs your local `opencode` CLI- `cursor`: runs Cursor in background mode- `pi_local`: runs an embedded Pi agent locally-- `hermes_local`: runs your local `hermes` CLI (`hermes-paperclip-adapter`)+- `hermes_local`: starts your local `hermes` CLI through `@paperclipai/hermes-paperclip-adapter`+- `hermes_gateway`: calls an already-running Hermes API server through `@paperclipai/hermes-paperclip-adapter/gateway`- `openclaw_gateway`: connects to an OpenClaw gateway endpoint- `process`: generic shell command adapter- `http`: calls an external HTTP endpoint@@ -48,7 +49,7 @@ External plugin adapters (install via the adapter manager or API):- `droid_local`: runs your local Factory Droid CLI (`@henkey/droid-paperclip-adapter`)-For local CLI adapters (`claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `droid_local`), Paperclip assumes the CLI is already installed and authenticated on the host machine.+For local CLI adapters (`claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `droid_local`), Paperclip assumes the CLI is already installed and authenticated on the host machine. For `hermes_gateway`, Paperclip assumes the Hermes API server is already running, reachable from the Paperclip server, and configured with an API key. The older `@paperclipai/adapter-hermes-gateway` npm package is only a deprecated compatibility shim; the adapter type remains `hermes_gateway`.## 3.2 Runtime behavior@@ -177,7 +178,7 @@ Start with least privilege where possible, and avoid exposing secrets in broad r## 10. Minimal setup checklist-1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `cursor`, or `openclaw_gateway`). External plugins like `droid_local` are also available via the adapter manager.+1. Choose adapter (e.g. `claude_local`, `codex_local`, `opencode_local`, `hermes_local`, `hermes_gateway`, `cursor`, or `openclaw_gateway`). External plugins like `droid_local` are also available via the adapter manager.2. Set `cwd` to the target workspace (for local adapters).3. Optionally add a prompt template (`promptTemplate`) or use the managed instructions bundle.4. Configure heartbeat policy (timer and/or assignment wakeups).diff --git a/docs/guides/board-operator/managing-agents.md b/docs/guides/board-operator/managing-agents.mdindex 4850222d0a..1ada4ec87e 100644--- a/docs/guides/board-operator/managing-agents.md+++ b/docs/guides/board-operator/managing-agents.md@@ -28,10 +28,15 @@ Create agents from the Agents page. Each agent requires:- **Capabilities** — short description of what this agent doesCommon adapter choices:-- `claude_local` / `codex_local` / `opencode_local` for local coding agents-- `openclaw_gateway` / `http` for webhook-based external agents+- `claude_local` / `codex_local` / `opencode_local` / `hermes_local` for local coding agents+- `hermes_gateway` / `openclaw_gateway` / `http` for webhook-based external agents- `process` for generic local command execution+Use `hermes_local` when Paperclip should start the local Hermes CLI. Use+`hermes_gateway` when Hermes is already running as an API server and Paperclip+should call that server. Both are built-in adapter types from the unified+`@paperclipai/hermes-paperclip-adapter` package.+For `opencode_local`, configure an explicit `adapterConfig.model` (`provider/model`).Paperclip validates the selected model against live `opencode models` output.diff --git a/package.json b/package.jsonindex 501b53a34d..75007b518d 100644--- a/package.json+++ b/package.json@@ -38,7 +38,10 @@"check:tokens": "node scripts/check-forbidden-tokens.mjs","check:no-git-push": "node scripts/check-no-git-push.mjs","test:check-no-git-push": "node --test scripts/check-no-git-push.test.mjs",+ "test:hermes-gateway-smoke": "node --test scripts/smoke/hermes-gateway-smoke.test.mjs","docs:dev": "cd docs && npx mintlify dev",+ "smoke:hermes-gateway-join": "./scripts/smoke/hermes-gateway-join.sh",+ "smoke:hermes-gateway-e2e": "./scripts/smoke/hermes-gateway-e2e.sh","smoke:openclaw-join": "./scripts/smoke/openclaw-join.sh","smoke:openclaw-docker-ui": "./scripts/smoke/openclaw-docker-ui.sh","smoke:openclaw-sse-standalone": "./scripts/smoke/openclaw-sse-standalone.sh",diff --git a/packages/adapters/hermes-gateway/README.md b/packages/adapters/hermes-gateway/README.mdnew file mode 100644index 0000000000..736930357b--- /dev/null+++ b/packages/adapters/hermes-gateway/README.md@@ -0,0 +1,25 @@+# Hermes Gateway Adapter Compatibility Shim++`@paperclipai/adapter-hermes-gateway` is a deprecated compatibility shim.++Use `@paperclipai/hermes-paperclip-adapter` for new installs and import gateway+entrypoints from `@paperclipai/hermes-paperclip-adapter/gateway`. The adapter+type remains `hermes_gateway`; only package ownership changed.++`hermes_gateway` is for an already-running Hermes API server. It does not start+the local Hermes CLI. If Paperclip should launch local `hermes chat` as a child+process, use `hermes_local` from `@paperclipai/hermes-paperclip-adapter`+instead.++The shim preserves the legacy exports for one release:++- `.`+- `./server`+- `./ui`+- `./cli`+- `./ui-parser`++These exports forward to the unified Hermes package. Existing+`@paperclipai/adapter-hermes-gateway` plugin installs should continue to load+during the compatibility window, but should migrate to+`@paperclipai/hermes-paperclip-adapter` before the shim is removed.diff --git a/packages/adapters/hermes-gateway/package.json b/packages/adapters/hermes-gateway/package.jsonnew file mode 100644index 0000000000..f9fb40cc3c--- /dev/null+++ b/packages/adapters/hermes-gateway/package.json@@ -0,0 +1,81 @@+{+ "name": "@paperclipai/adapter-hermes-gateway",+ "version": "0.1.0",+ "description": "Deprecated compatibility shim for Hermes Gateway; use @paperclipai/hermes-paperclip-adapter/gateway",+ "type": "module",+ "license": "MIT",+ "author": "Paperclip",+ "repository": {+ "type": "git",+ "url": "https://github.com/paperclipai/paperclip",+ "directory": "packages/adapters/hermes-gateway"+ },+ "bugs": {+ "url": "https://github.com/paperclipai/paperclip/issues"+ },+ "homepage": "https://github.com/paperclipai/paperclip/tree/master/packages/adapters/hermes#readme",+ "keywords": [+ "paperclip",+ "hermes",+ "gateway",+ "adapter",+ "orchestration"+ ],+ "exports": {+ ".": "./src/index.ts",+ "./server": "./src/server/index.ts",+ "./ui": "./src/ui/index.ts",+ "./cli": "./src/cli/index.ts",+ "./ui-parser": "./ui-parser.cjs"+ },+ "paperclip": {+ "adapterUiParser": "1.0.0"+ },+ "publishConfig": {+ "access": "public",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js"+ },+ "./server": {+ "types": "./dist/server/index.d.ts",+ "import": "./dist/server/index.js"+ },+ "./ui": {+ "types": "./dist/ui/index.d.ts",+ "import": "./dist/ui/index.js"+ },+ "./cli": {+ "types": "./dist/cli/index.d.ts",+ "import": "./dist/cli/index.js"+ },+ "./ui-parser": "./ui-parser.cjs"+ },+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts",+ "provenance": true+ },+ "files": [+ "dist",+ "ui-parser.cjs",+ "README.md"+ ],+ "scripts": {+ "build": "tsc",+ "clean": "rm -rf dist",+ "typecheck": "tsc --noEmit",+ "test": "vitest run"+ },+ "dependencies": {+ "@paperclipai/hermes-paperclip-adapter": "workspace:*"+ },+ "devDependencies": {+ "@types/node": "^22.19.21",+ "typescript": "^5.7.3",+ "vitest": "^4.1.8"+ },+ "engines": {+ "node": ">=20.0.0"+ }+}diff --git a/packages/adapters/hermes-gateway/src/cli/index.ts b/packages/adapters/hermes-gateway/src/cli/index.tsnew file mode 100644index 0000000000..0ecd76a446--- /dev/null+++ b/packages/adapters/hermes-gateway/src/cli/index.ts@@ -0,0 +1 @@+export { formatStdoutEvent } from "@paperclipai/hermes-paperclip-adapter/gateway/cli";diff --git a/packages/adapters/hermes-gateway/src/index.ts b/packages/adapters/hermes-gateway/src/index.tsnew file mode 100644index 0000000000..36e1cdc54f--- /dev/null+++ b/packages/adapters/hermes-gateway/src/index.ts@@ -0,0 +1,7 @@+export {+ agentConfigurationDoc,+ createServerAdapter,+ label,+ models,+ type,+} from "@paperclipai/hermes-paperclip-adapter/gateway";diff --git a/packages/adapters/hermes-gateway/src/server/index.ts b/packages/adapters/hermes-gateway/src/server/index.tsnew file mode 100644index 0000000000..eebc096eb7--- /dev/null+++ b/packages/adapters/hermes-gateway/src/server/index.ts@@ -0,0 +1,9 @@+export {+ execute,+ getConfigSchema,+ mapFinalResultForTest,+ parseSseFramesForTest,+ resolveSessionKey,+ sessionCodec,+ testEnvironment,+} from "@paperclipai/hermes-paperclip-adapter/gateway/server";diff --git a/packages/adapters/hermes-gateway/src/ui/index.ts b/packages/adapters/hermes-gateway/src/ui/index.tsnew file mode 100644index 0000000000..1f5105a6e4--- /dev/null+++ b/packages/adapters/hermes-gateway/src/ui/index.ts@@ -0,0 +1 @@+export { parseStdoutLine } from "@paperclipai/hermes-paperclip-adapter/gateway/ui";diff --git a/packages/adapters/hermes-gateway/tsconfig.json b/packages/adapters/hermes-gateway/tsconfig.jsonnew file mode 100644index 0000000000..8fea361a34--- /dev/null+++ b/packages/adapters/hermes-gateway/tsconfig.json@@ -0,0 +1,9 @@+{+ "extends": "../../../tsconfig.base.json",+ "compilerOptions": {+ "outDir": "dist",+ "rootDir": "src",+ "types": ["node"]+ },+ "include": ["src"]+}diff --git a/packages/adapters/hermes-gateway/ui-parser.cjs b/packages/adapters/hermes-gateway/ui-parser.cjsnew file mode 100644index 0000000000..9b2e7fa0ce--- /dev/null+++ b/packages/adapters/hermes-gateway/ui-parser.cjs@@ -0,0 +1 @@+module.exports = require("@paperclipai/hermes-paperclip-adapter/gateway/ui-parser");diff --git a/packages/adapters/hermes-gateway/vitest.config.ts b/packages/adapters/hermes-gateway/vitest.config.tsnew file mode 100644index 0000000000..ad7d95889a--- /dev/null+++ b/packages/adapters/hermes-gateway/vitest.config.ts@@ -0,0 +1,8 @@+import { defineConfig } from "vitest/config";++export default defineConfig({+ test: {+ environment: "node",+ exclude: ["dist/**", "node_modules/**"],+ },+});diff --git a/packages/adapters/hermes/LICENSE b/packages/adapters/hermes/LICENSEnew file mode 100644index 0000000000..5700b99782--- /dev/null+++ b/packages/adapters/hermes/LICENSE@@ -0,0 +1,21 @@+MIT License++Copyright (c) 2026 Nous Research++Permission is hereby granted, free of charge, to any person obtaining a copy+of this software and associated documentation files (the "Software"), to deal+in the Software without restriction, including without limitation the rights+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell+copies of the Software, and to permit persons to whom the Software is+furnished to do so, subject to the following conditions:++The above copyright notice and this permission notice shall be included in all+copies or substantial portions of the Software.++THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE+SOFTWARE.diff --git a/packages/adapters/hermes/README.md b/packages/adapters/hermes/README.mdnew file mode 100644index 0000000000..53c4ca3901--- /dev/null+++ b/packages/adapters/hermes/README.md@@ -0,0 +1,335 @@+# Paperclip Adapters for Hermes Agent++A [Paperclip](https://paperclip.ing) adapter package that lets you run [Hermes Agent](https://github.com/NousResearch/hermes-agent) as a managed employee in a Paperclip company.++Hermes Agent is a full-featured AI agent by [Nous Research](https://nousresearch.com) with 30+ native tools, persistent memory, session persistence, 80+ skills, MCP support, and multi-provider model access.++This package owns both built-in Hermes adapter types:++- `hermes_local` runs the local Hermes CLI as a child process. The package root exports remain compatible with the original local adapter.+- `hermes_gateway` calls an already-running Hermes API server over HTTP/SSE. Gateway entrypoints live under the `./gateway` export namespace.++Choose `hermes_local` when Paperclip and Hermes run on the same trusted host+and Paperclip should start `hermes chat` for each heartbeat. Choose+`hermes_gateway` when Hermes is already running as an API server, often on+another host, in Docker, or behind a private-network/TLS endpoint. The adapter+type keys did not change during package consolidation.++## Key Features++This adapter provides:++- **8 inference providers** — Anthropic, OpenRouter, OpenAI, Nous, OpenAI Codex, ZAI, Kimi Coding, MiniMax+- **Skills integration** — Scans both Paperclip-managed and Hermes-native skills (`~/.hermes/skills/`), with sync/list/resolve APIs+- **Structured transcript parsing** — Raw Hermes stdout is parsed into typed `TranscriptEntry` objects so Paperclip renders proper tool cards with status icons and expand/collapse+- **Rich post-processing** — Converts Hermes ASCII banners, setext headings, and `+--+` table borders into clean GFM markdown+- **Comment-driven wakes** — Agents wake to respond to issue comments, not just task assignments+- **Auto model detection** — Reads `~/.hermes/config.yaml` to pre-populate the UI with the user's configured model+- **Session codec** — Structured validation and migration of session state across heartbeats+- **Benign stderr reclassification** — MCP init messages and structured logs are reclassified so they don't appear as errors in the UI+- **Session source tagging** — Sessions are tagged as `tool` source so they don't clutter the user's interactive history+- **Filesystem checkpoints** — Optional `--checkpoints` for rollback safety+- **Thinking effort control** — Passes `--reasoning-effort` for thinking/reasoning models++### Hermes Agent Capabilities++| Feature | Claude Code | Codex | Hermes Agent |+|---------|------------|-------|-------------|+| Persistent memory | ❌ | ❌ | ✅ Remembers across sessions |+| Native tools | ~5 | ~5 | 30+ (terminal, file, web, browser, vision, git, etc.) |+| Skills system | ❌ | ❌ | ✅ 80+ loadable skills |+| Session search | ❌ | ❌ | ✅ FTS5 search over past conversations |+| Sub-agent delegation | ❌ | ❌ | ✅ Parallel sub-tasks |+| Context compression | ❌ | ❌ | ✅ Auto-compresses long conversations |+| MCP client | ❌ | ❌ | ✅ Connect to any MCP server |+| Multi-provider | Anthropic only | OpenAI only | ✅ 8 providers out of the box |++## Installation++This package ships with Paperclip core as the built-in `hermes_local` and+`hermes_gateway` adapters. No Adapter manager installation is required for+normal Paperclip use.++### Prerequisites++- [Hermes Agent](https://github.com/NousResearch/hermes-agent) installed (`pip install hermes-agent`)+- Python 3.10++- At least one LLM API key (Anthropic, OpenRouter, or OpenAI)++## Quick Start++### 1. Optional: override the built-in for adapter development++For local adapter development, install the package from a local path in Adapter+manager, or add an entry to `~/.paperclip/adapter-plugins.json` and restart+Paperclip. The external package can override either built-in Hermes adapter+while it is enabled:++```json+[+ {+ "packageName": "@paperclipai/hermes-paperclip-adapter",+ "localPath": "/absolute/path/to/paperclip/packages/adapters/hermes",+ "type": "hermes_local",+ "installedAt": "2026-06-23T00:00:00.000Z"+ }+]+```++Use `"type": "hermes_gateway"` with the same package when testing a gateway+override.++The package root exports `createServerAdapter()` for the local server adapter,+a declarative config schema for the generic agent form, and `./ui-parser` for+local run transcript parsing. Gateway entrypoints are exported from `./gateway`,+`./gateway/server`, `./gateway/ui`, `./gateway/cli`, and `./gateway/ui-parser`.+Paperclip core imports these same package entrypoints for built-in adapter+registration.++### 2. Create a local Hermes agent in Paperclip++In the Paperclip UI or via API, create an agent with adapter type `hermes_local`:++```json+{+ "name": "Hermes Engineer",+ "adapterType": "hermes_local",+ "adapterConfig": {+ "model": "anthropic/claude-sonnet-4",+ "maxIterations": 50,+ "timeoutSec": 300,+ "persistSession": true,+ "enabledToolsets": ["terminal", "file", "web"]+ }+}+```++This mode shells out to the local `hermes` CLI. Paperclip injects runtime+environment variables and captures stdout/stderr from the child process.++### 3. Create a Hermes gateway agent in Paperclip++Start Hermes with its API server enabled first:++```bash+API_SERVER_ENABLED=true \+API_SERVER_KEY=<generated-secret> \+hermes gateway run --replace --accept-hooks+```++Then create an agent with adapter type `hermes_gateway`:++```json+{+ "name": "Hermes Gateway Engineer",+ "adapterType": "hermes_gateway",+ "adapterConfig": {+ "apiBaseUrl": "http://127.0.0.1:8642",+ "apiKey": "<same-value-as-API_SERVER_KEY>",+ "paperclipApiUrl": "http://127.0.0.1:3100",+ "sessionKeyStrategy": "issue",+ "timeoutSec": 120+ }+}+```++This mode does not start Hermes. It creates runs with `POST /v1/runs`, streams+Hermes events with SSE, polls run status as a fallback, and stops timed-out runs+with `POST /v1/runs/{run_id}/stop`.++### Compatibility with the old gateway package++`@paperclipai/adapter-hermes-gateway` remains as a deprecated compatibility shim+for one release. It re-exports the gateway entrypoints from+`@paperclipai/hermes-paperclip-adapter/gateway` and preserves the legacy exports+for existing plugin installs. New installs and built-in Paperclip registrations+should use `@paperclipai/hermes-paperclip-adapter`; the adapter type remains+`hermes_gateway`.++### Runtime API guidance++Hermes receives Paperclip runtime identity through environment variables:++- `PAPERCLIP_API_URL`+- `PAPERCLIP_API_KEY`+- `PAPERCLIP_RUN_ID`++Prompts should reference those variables directly. Command output may redact+secret values, so do not copy printed tokens into comments or config. Use+`Authorization: Bearer $PAPERCLIP_API_KEY` on Paperclip API requests and+`X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID` on mutating issue requests. For+multiline comments or status updates, preserve newlines with a heredoc plus+`jq --arg`.++### Hermes-originated Paperclip tasks++The package includes a Hermes skill/helper for the reverse direction: a user+starts in Hermes and asks Hermes to create or update Paperclip work. This is not+the same as Paperclip waking Hermes through `hermes_local` or `hermes_gateway`.++Configure Paperclip access in Hermes env/profile secrets, not prompt text:++```bash+PAPERCLIP_API_URL=http://127.0.0.1:3100/api+PAPERCLIP_BRIDGE_API_KEY=<task-bridge-scoped-agent-api-key>+```++Optional env values:++- `PAPERCLIP_COMPANY_ID`+- `PAPERCLIP_AGENT_ID`+- `PAPERCLIP_RUN_ID`++The bundled `paperclip-task-bridge` skill provides deterministic helper+commands:++```bash+node ./paperclip-task.mjs list-assigned+node ./paperclip-task.mjs create-task --parent-id "<approved-parent-issue-id>" --title "Investigate checkout failures" --description "Capture failing request and root cause."+node ./paperclip-task.mjs comment --issue PAP-123 --body "Found the failing request path."+node ./paperclip-task.mjs update-status --issue PAP-123 --status in_review --comment "Ready for review."+```++The helper reads credentials from environment variables and prints only JSON+summaries. It supports `create-task`, `comment`, `update-status`, and+`list-assigned`.++Create the bridge key with `scope.kind = "task_bridge"` plus a `parentIssueId`+or `projectId` boundary. Do not use a normal claimed agent API key for+internet-facing Hermes chat/webhook task-bridge operations.++### 4. Assign work++Create issues in Paperclip and assign them to your Hermes agent. On each heartbeat, Hermes will:++1. Receive the task instructions+2. Use its full tool suite to complete the work+3. Report results back to Paperclip+4. Persist session state for continuity++## Configuration Reference++### Core++| Field | Type | Default | Description |+|-------|------|---------|-------------|+| `model` | string | `anthropic/claude-sonnet-4` | Model in `provider/model` format |+| `provider` | string | *(auto-detected)* | API provider: `auto`, `openrouter`, `nous`, `openai-codex`, `zai`, `kimi-coding`, `minimax`, `minimax-cn` |+| `timeoutSec` | number | `300` | Execution timeout in seconds |+| `graceSec` | number | `10` | Grace period before SIGKILL |++### Tools++| Field | Type | Default | Description |+|-------|------|---------|-------------|+| `toolsets` | string | *(all)* | Comma-separated toolsets to enable (e.g. `"terminal,file,web"`) |++Available toolsets: `terminal`, `file`, `web`, `browser`, `code_execution`, `vision`, `mcp`, `creative`, `productivity`++### Session & Workspace++| Field | Type | Default | Description |+|-------|------|---------|-------------|+| `persistSession` | boolean | `true` | Resume sessions across heartbeats |+| `worktreeMode` | boolean | `false` | Git worktree isolation |+| `checkpoints` | boolean | `false` | Enable filesystem checkpoints for rollback |++### Advanced++| Field | Type | Default | Description |+|-------|------|---------|-------------|+| `hermesCommand` | string | `hermes` | Custom CLI binary path |+| `verbose` | boolean | `false` | Enable verbose output |+| `quiet` | boolean | `true` | Quiet mode (clean output, no banner/spinner) |+| `extraArgs` | string[] | `[]` | Additional CLI arguments |+| `env` | object | `{}` | Extra environment variables |+| `promptTemplate` | string | *(built-in)* | Custom prompt template |+| `paperclipApiUrl` | string | `http://127.0.0.1:3100/api` | Paperclip API base URL |++### Prompt Template Variables++Use `{{variable}}` syntax in `promptTemplate`:++| Variable | Description |+|----------|-------------|+| `{{agentId}}` | Paperclip agent ID |+| `{{agentName}}` | Agent display name |+| `{{companyId}}` | Company ID |+| `{{companyName}}` | Company name |+| `{{runId}}` | Current heartbeat run ID |+| `{{taskId}}` | Assigned task/issue ID |+| `{{taskTitle}}` | Task title |+| `{{taskBody}}` | Task instructions |+| `{{projectName}}` | Project name |+| `{{paperclipApiUrl}}` | Paperclip API base URL |+| `{{commentId}}` | Comment ID (when woken by a comment) |+| `{{wakeReason}}` | Reason this run was triggered |++Conditional sections:++- `{{#taskId}}...{{/taskId}}` — included only when a task is assigned+- `{{#noTask}}...{{/noTask}}` — included only when no task (heartbeat check)+- `{{#commentId}}...{{/commentId}}` — included only when woken by a comment++## Architecture++```+Paperclip Hermes Agent+┌──────────────────┐ ┌──────────────────┐+│ Heartbeat │ │ │+│ Scheduler │───execute()──▶│ hermes chat -q │+│ │ │ │+│ Issue System │ │ 30+ Tools │+│ Comment Wakes │◀──results─────│ Memory System │+│ │ │ Session DB │+│ Cost Tracking │ │ Skills │+│ │ │ MCP Client │+│ Skill Sync │◀──snapshot────│ ~/.hermes/skills│+│ Org Chart │ │ │+└──────────────────┘ └──────────────────┘+```++The adapter spawns Hermes Agent's CLI in single-query mode (`-q`). Hermes+processes the task using its full tool suite, then exits. The adapter:++1. **Captures** stdout/stderr and parses token usage, session IDs, and cost+2. **Parses** raw output into structured `TranscriptEntry` objects (tool cards with status icons)+3. **Post-processes** Hermes ASCII formatting (banners, setext headings, table borders) into clean GFM markdown+4. **Reclassifies** benign stderr (MCP init, structured logs) so they don't show as errors+5. **Tags** sessions as `tool` source to keep them separate from interactive usage+6. **Reports** results back to Paperclip with cost, usage, and session state++Session persistence works via Hermes's `--resume` flag — each run picks+up where the last one left off, maintaining conversation context,+memories, and tool state across heartbeats. The `sessionCodec` validates+and migrates session state between runs.++### Skills Integration++The adapter scans two skill sources and merges them:++- **Paperclip-managed skills** — bundled with the adapter, togglable from the UI+- **Hermes-native skills** — from `~/.hermes/skills/`, read-only, always loaded++The `listSkills` / `syncSkills` APIs expose a unified snapshot so the+Paperclip UI can display both managed and native skills in one view.++## Development++```bash+git clone https://github.com/paperclipai/paperclip+cd paperclip/packages/adapters/hermes+pnpm install+pnpm build+```++## License++MIT — see [LICENSE](LICENSE)++## Links++- [Hermes Agent](https://github.com/NousResearch/hermes-agent) — The AI agent this adapter runs+- [Paperclip](https://github.com/paperclipai/paperclip) — The orchestration platform+- [Nous Research](https://nousresearch.com) — The team behind Hermes+- [Paperclip Docs](https://paperclip.ing/docs) — Paperclip documentationdiff --git a/packages/adapters/hermes/gateway-ui-parser.cjs b/packages/adapters/hermes/gateway-ui-parser.cjsnew file mode 100644index 0000000000..1cba319c8d--- /dev/null+++ b/packages/adapters/hermes/gateway-ui-parser.cjs@@ -0,0 +1,49 @@+"use strict";++function safeJsonParse(text) {+ try {+ return JSON.parse(text);+ } catch {+ return null;+ }+}++function asRecord(value) {+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;+ return value;+}++function asString(value) {+ return typeof value === "string" ? value : "";+}++function parseStdoutLine(line, ts) {+ const trimmed = line.trim();+ if (!trimmed) return [];++ const eventMatch = trimmed.match(/^\[hermes-gateway:event\]\s+run=([^\s]+)\s+event=([^\s]+)\s+data=(.*)$/s);+ if (eventMatch) {+ const eventName = eventMatch[2];+ const data = asRecord(safeJsonParse(eventMatch[3]));+ if (eventName === "message.delta") {+ const delta = asString(data && data.delta) || asString(data && data.text_delta);+ return delta ? [{ kind: "assistant", ts, text: delta, delta: true }] : [];+ }+ if (eventName === "run.failed" || eventName === "run.error") {+ const message = asString(data && data.error) || asString(data && data.message) || "Hermes run failed";+ return [{ kind: "stderr", ts, text: message }];+ }+ if (eventName === "reasoning.available") {+ return [{ kind: "thinking", ts, text: "Hermes reasoning available" }];+ }+ return [{ kind: "system", ts, text: `Hermes event: ${eventName}` }];+ }++ if (trimmed.startsWith("[hermes-gateway]")) {+ return [{ kind: "system", ts, text: trimmed.replace(/^\[hermes-gateway\]\s*/, "") }];+ }++ return [{ kind: "stdout", ts, text: line }];+}++module.exports = { parseStdoutLine };diff --git a/packages/adapters/hermes/package.json b/packages/adapters/hermes/package.jsonnew file mode 100644index 0000000000..356c049d9d--- /dev/null+++ b/packages/adapters/hermes/package.json@@ -0,0 +1,113 @@+{+ "name": "@paperclipai/hermes-paperclip-adapter",+ "version": "0.3.1",+ "description": "Paperclip adapters for Hermes Agent local CLI and Hermes Gateway HTTP/SSE runs",+ "type": "module",+ "license": "MIT",+ "author": "Paperclip",+ "repository": {+ "type": "git",+ "url": "https://github.com/paperclipai/paperclip",+ "directory": "packages/adapters/hermes"+ },+ "bugs": {+ "url": "https://github.com/paperclipai/paperclip/issues"+ },+ "homepage": "https://github.com/paperclipai/paperclip/tree/master/packages/adapters/hermes#readme",+ "keywords": [+ "paperclip",+ "hermes",+ "hermes-agent",+ "ai-agent",+ "adapter",+ "orchestration"+ ],+ "exports": {+ ".": "./src/index.ts",+ "./server": "./src/server/index.ts",+ "./ui": "./src/ui/index.ts",+ "./cli": "./src/cli/index.ts",+ "./ui-parser": "./ui-parser.cjs",+ "./gateway": "./src/gateway/index.ts",+ "./gateway/server": "./src/gateway/server/index.ts",+ "./gateway/ui": "./src/gateway/ui/index.ts",+ "./gateway/cli": "./src/gateway/cli/index.ts",+ "./gateway/ui-parser": "./gateway-ui-parser.cjs"+ },+ "paperclip": {+ "adapterUiParser": "1.0.0"+ },+ "publishConfig": {+ "access": "public",+ "exports": {+ ".": {+ "types": "./dist/index.d.ts",+ "import": "./dist/index.js"+ },+ "./server": {+ "types": "./dist/server/index.d.ts",+ "import": "./dist/server/index.js"+ },+ "./ui": {+ "types": "./dist/ui/index.d.ts",+ "import": "./dist/ui/index.js"+ },+ "./cli": {+ "types": "./dist/cli/index.d.ts",+ "import": "./dist/cli/index.js"+ },+ "./ui-parser": "./ui-parser.cjs",+ "./gateway": {+ "types": "./dist/gateway/index.d.ts",+ "import": "./dist/gateway/index.js"+ },+ "./gateway/server": {+ "types": "./dist/gateway/server/index.d.ts",+ "import": "./dist/gateway/server/index.js"+ },+ "./gateway/ui": {+ "types": "./dist/gateway/ui/index.d.ts",+ "import": "./dist/gateway/ui/index.js"+ },+ "./gateway/cli": {+ "types": "./dist/gateway/cli/index.d.ts",+ "import": "./dist/gateway/cli/index.js"+ },+ "./gateway/ui-parser": "./gateway-ui-parser.cjs"+ },+ "main": "./dist/index.js",+ "types": "./dist/index.d.ts",+ "provenance": true+ },+ "files": [+ "dist",+ "skills",+ "ui-parser.cjs",+ "gateway-ui-parser.cjs",+ "README.md",+ "LICENSE"+ ],+ "scripts": {+ "build": "tsc",+ "dev": "tsc --watch",+ "lint": "eslint src/",+ "typecheck": "tsc --noEmit",+ "test": "vitest run",+ "test:command-resolution": "vitest run src/server/command-resolution.test.ts",+ "prepack": "node scripts/prepare-publish-package.mjs",+ "postpack": "node scripts/restore-dev-package.mjs",+ "clean": "rm -rf dist"+ },+ "dependencies": {+ "@paperclipai/adapter-utils": "workspace:*",+ "picocolors": "^1.1.1"+ },+ "devDependencies": {+ "@types/node": "^22.19.21",+ "typescript": "^5.7.3",+ "vitest": "^4.1.8"+ },+ "engines": {+ "node": ">=20.0.0"+ }+}diff --git a/packages/adapters/hermes/scripts/prepare-publish-package.mjs b/packages/adapters/hermes/scripts/prepare-publish-package.mjsnew file mode 100644index 0000000000..b004c53f8b--- /dev/null+++ b/packages/adapters/hermes/scripts/prepare-publish-package.mjs@@ -0,0 +1,106 @@+#!/usr/bin/env node+import { existsSync, readFileSync, readdirSync, renameSync, writeFileSync } from "node:fs";+import { dirname, join, resolve } from "node:path";+import { fileURLToPath } from "node:url";++const scriptDir = dirname(fileURLToPath(import.meta.url));+const packageDir = resolve(scriptDir, "..");+const packageJsonPath = join(packageDir, "package.json");+const devPackageJsonPath = join(packageDir, "package.dev.json");++function findRepoRoot(startDir) {+ let current = startDir;+ while (current !== dirname(current)) {+ if (existsSync(join(current, "pnpm-workspace.yaml"))) {+ return current;+ }+ current = dirname(current);+ }+ return null;+}++function readJson(filePath) {+ return JSON.parse(readFileSync(filePath, "utf8"));+}++function collectWorkspaceVersions(repoRoot) {+ const roots = ["packages", "server", "ui", "cli"];+ const versions = new Map();++ function walk(relDir) {+ const absDir = join(repoRoot, relDir);+ if (!existsSync(absDir)) return;++ const pkgPath = join(absDir, "package.json");+ if (existsSync(pkgPath)) {+ const pkg = readJson(pkgPath);+ if (pkg.name && pkg.version) {+ versions.set(pkg.name, pkg.version);+ }+ return;+ }++ for (const entry of readdirSync(absDir, { withFileTypes: true })) {+ if (!entry.isDirectory()) continue;+ if (entry.name === "node_modules" || entry.name === "dist" || entry.name === ".git") continue;+ walk(join(relDir, entry.name));+ }+ }++ for (const root of roots) {+ walk(root);+ }++ return versions;+}++function rewriteWorkspaceDeps(deps, workspaceVersions) {+ if (!deps) return deps;+ return Object.fromEntries(+ Object.entries(deps).map(([name, version]) => {+ if (typeof version !== "string" || !version.startsWith("workspace:")) {+ return [name, version];+ }++ const resolvedVersion = workspaceVersions.get(name);+ if (!resolvedVersion) {+ throw new Error(`Cannot resolve workspace dependency ${name} for publish package`);+ }+ return [name, resolvedVersion];+ }),+ );+}++const pkg = readJson(packageJsonPath);+const publishConfig = pkg.publishConfig ?? {};++if (existsSync(devPackageJsonPath)) {+ throw new Error(`Refusing to overwrite existing ${devPackageJsonPath}`);+}++if (!publishConfig.exports) {+ throw new Error(`${pkg.name} is missing publishConfig.exports`);+}++const repoRoot = findRepoRoot(packageDir);+const workspaceVersions = repoRoot ? collectWorkspaceVersions(repoRoot) : new Map();++renameSync(packageJsonPath, devPackageJsonPath);++const nextPublishConfig = { ...publishConfig };+delete nextPublishConfig.exports;+delete nextPublishConfig.main;+delete nextPublishConfig.types;++const publishPkg = {+ ...pkg,+ exports: publishConfig.exports,+ main: publishConfig.main,+ types: publishConfig.types,+ publishConfig: nextPublishConfig,+ dependencies: rewriteWorkspaceDeps(pkg.dependencies, workspaceVersions),+ optionalDependencies: rewriteWorkspaceDeps(pkg.optionalDependencies, workspaceVersions),+ peerDependencies: rewriteWorkspaceDeps(pkg.peerDependencies, workspaceVersions),+};++writeFileSync(packageJsonPath, `${JSON.stringify(publishPkg, null, 2)}\n`);diff --git a/packages/adapters/hermes/scripts/restore-dev-package.mjs b/packages/adapters/hermes/scripts/restore-dev-package.mjsnew file mode 100644index 0000000000..33e24fc04f--- /dev/null+++ b/packages/adapters/hermes/scripts/restore-dev-package.mjs@@ -0,0 +1,14 @@+#!/usr/bin/env node+import { existsSync, renameSync, rmSync } from "node:fs";+import { dirname, join, resolve } from "node:path";+import { fileURLToPath } from "node:url";++const scriptDir = dirname(fileURLToPath(import.meta.url));+const packageDir = resolve(scriptDir, "..");+const packageJsonPath = join(packageDir, "package.json");+const devPackageJsonPath = join(packageDir, "package.dev.json");++if (existsSync(devPackageJsonPath)) {+ rmSync(packageJsonPath, { force: true });+ renameSync(devPackageJsonPath, packageJsonPath);+}diff --git a/packages/adapters/hermes/skills/paperclip-task-bridge/SKILL.md b/packages/adapters/hermes/skills/paperclip-task-bridge/SKILL.mdnew file mode 100644index 0000000000..b325cec516--- /dev/null+++ b/packages/adapters/hermes/skills/paperclip-task-bridge/SKILL.md@@ -0,0 +1,77 @@+---+name: paperclip-task-bridge+description: Create, comment on, update, and list Paperclip tasks from Hermes using scoped Paperclip API credentials.+---++# Paperclip Task Bridge++Use this skill when a Hermes-originated request needs to create or update Paperclip work directly. This is the Hermes-to-Paperclip direction, separate from Paperclip waking Hermes through the `hermes_local` or `hermes_gateway` adapter.++## Required Environment++Configure these in Hermes env/profile secrets, not in prompt text:++- `PAPERCLIP_API_URL` - Paperclip base URL, with or without `/api`.+- `PAPERCLIP_BRIDGE_API_KEY` - a Paperclip agent API key created with `scope.kind = "task_bridge"`.++Optional:++- `PAPERCLIP_API_KEY` - fallback env var for older profiles; it must still contain a `task_bridge` scoped key, never a full agent key.+- `PAPERCLIP_COMPANY_ID` - skips one identity lookup when set.+- `PAPERCLIP_AGENT_ID` - skips one identity lookup when set.+- `PAPERCLIP_RUN_ID` - sent as `X-Paperclip-Run-Id` on mutating requests when Hermes is running inside a Paperclip heartbeat.++Never print or paste API keys. The helper reads credentials from environment variables and only prints response summaries. Do not put a normal claimed agent API key in an internet-facing Hermes runtime; normal keys can use broad same-company Paperclip routes.++## Create a Bridge Key++Create the key from a board-authenticated Paperclip API session and store the returned token once:++```sh+curl -X POST "$PAPERCLIP_API_URL/api/agents/$HERMES_AGENT_ID/keys" \+ -H "Authorization: Bearer $BOARD_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{+ "name": "Hermes task bridge",+ "scope": {+ "kind": "task_bridge",+ "parentIssueId": "00000000-0000-4000-8000-000000000000"+ }+ }'+```++Use `parentIssueId` or `parentIssueIds` when Hermes should only create child tasks under approved work. Use `projectId` or `projectIds` when the approved boundary is a project. A bridge key can create tasks only inside that boundary, can comment/update only bridge-created or assigned issues, and cannot use company-wide issue list/search/read surfaces.++## Helper++Run the helper from this skill directory:++```sh+node ./paperclip-task.mjs --help+```++Commands:++```sh+node ./paperclip-task.mjs list-assigned+node ./paperclip-task.mjs create-task --parent-id "00000000-0000-4000-8000-000000000000" --title "Investigate checkout failures" --description "Capture failing request and root cause."+node ./paperclip-task.mjs comment --issue PAP-123 --body "Found the failing request path."+node ./paperclip-task.mjs update-status --issue PAP-123 --status in_review --comment "Ready for review."+```++`create-task` defaults to assigning the task to the authenticated Hermes agent so the work is immediately actionable. Use `--unassigned` to create backlog work instead. Use `--assignee-agent-id <uuid>` only when the Paperclip API key has permission to assign work to that agent.++For multiline bodies, prefer files or stdin:++```sh+node ./paperclip-task.mjs create-task --title "Write rollout note" --description-file ./task.md+node ./paperclip-task.mjs comment --issue PAP-123 --body-file -+```++## Workflow Expectations++- Keep tasks company-scoped by using the company resolved from the scoped agent key.+- Let Paperclip activity logging come from the normal API endpoints; do not write local logs that include credentials.+- Use comments for durable progress.+- Use `update-status` only when the issue has a real disposition: `done`, `in_review`, `blocked`, `todo`, `in_progress`, `backlog`, or `cancelled`.+- Use `list-assigned` before creating duplicate work when the user asks about current Paperclip assignments.diff --git a/packages/adapters/hermes/skills/paperclip-task-bridge/paperclip-task.mjs b/packages/adapters/hermes/skills/paperclip-task-bridge/paperclip-task.mjsnew file mode 100755index 0000000000..956e953281--- /dev/null+++ b/packages/adapters/hermes/skills/paperclip-task-bridge/paperclip-task.mjs@@ -0,0 +1,351 @@+#!/usr/bin/env node++import fs from "node:fs/promises";++const STATUSES = new Set(["backlog", "todo", "in_progress", "in_review", "done", "blocked", "cancelled"]);+const PRIORITIES = new Set(["critical", "high", "medium", "low"]);+const WORK_MODES = new Set(["standard", "ask", "planning"]);+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;++const HELP = `Paperclip task bridge for Hermes++Usage:+ paperclip-task.mjs list-assigned [--status todo,in_progress,in_review,blocked] [--limit 20]+ paperclip-task.mjs create-task --title <title> [--description <text>|--description-file <path|->] [options]+ paperclip-task.mjs comment --issue <id|identifier> (--body <text>|--body-file <path|->) [--resume|--reopen]+ paperclip-task.mjs update-status --issue <id|identifier> --status <status> [--comment <text>|--comment-file <path|->]++Environment:+ PAPERCLIP_API_URL Paperclip base URL, with or without /api.+ PAPERCLIP_BRIDGE_API_KEY+ Task-bridge Paperclip API key with kind=task_bridge scope.+ PAPERCLIP_API_KEY Fallback bridge key env var. Do not use a full agent key.+ PAPERCLIP_COMPANY_ID Optional company id override.+ PAPERCLIP_AGENT_ID Optional agent id override.+ PAPERCLIP_RUN_ID Optional run id for X-Paperclip-Run-Id on mutations.++create-task options:+ --assignee-agent-id <uuid|self> Assign to an agent. Defaults to self.+ --unassigned Create backlog/unassigned work.+ --parent-id <uuid> Parent issue id.+ --goal-id <uuid> Goal id.+ --project-id <uuid> Project id.+ --priority <critical|high|medium|low>+ --status <backlog|todo|in_progress|in_review|done|blocked|cancelled>+ --work-mode <standard|ask|planning>++Output is JSON and never includes credentials.`;++class UsageError extends Error {+ constructor(message) {+ super(message);+ this.name = "UsageError";+ }+}++class ApiError extends Error {+ constructor(status, body) {+ const message = typeof body?.error === "string" ? body.error : `Paperclip API request failed with status ${status}`;+ super(message);+ this.name = "ApiError";+ this.status = status;+ this.body = body;+ }+}++function parseArgs(argv) {+ const out = { _: [] };+ for (let i = 0; i < argv.length; i += 1) {+ const arg = argv[i];+ if (!arg.startsWith("--")) {+ out._.push(arg);+ continue;+ }+ const eq = arg.indexOf("=");+ if (eq !== -1) {+ out[arg.slice(2, eq)] = arg.slice(eq + 1);+ continue;+ }+ const key = arg.slice(2);+ const next = argv[i + 1];+ if (!next || next.startsWith("--")) {+ out[key] = true;+ continue;+ }+ out[key] = next;+ i += 1;+ }+ return out;+}++function readStringFlag(args, name) {+ const value = args[name];+ if (typeof value !== "string" || value.trim().length === 0) return null;+ return value;+}++function requireStringFlag(args, name) {+ const value = readStringFlag(args, name);+ if (!value) throw new UsageError(`Missing required --${name}`);+ return value;+}++function boolFlag(args, name) {+ return args[name] === true;+}++function normalizeApiBaseUrl(raw) {+ if (!raw || typeof raw !== "string" || raw.trim().length === 0) {+ throw new UsageError("PAPERCLIP_API_URL is required");+ }+ const trimmed = raw.trim().replace(/\/+$/, "");+ return trimmed.endsWith("/api") ? trimmed : `${trimmed}/api`;+}++function getConfig() {+ const apiKey = process.env.PAPERCLIP_BRIDGE_API_KEY?.trim() || process.env.PAPERCLIP_API_KEY?.trim();+ if (!apiKey) throw new UsageError("PAPERCLIP_BRIDGE_API_KEY is required");+ return {+ apiBaseUrl: normalizeApiBaseUrl(process.env.PAPERCLIP_API_URL),+ apiKey,+ runId: process.env.PAPERCLIP_RUN_ID?.trim() || null,+ companyId: process.env.PAPERCLIP_COMPANY_ID?.trim() || null,+ agentId: process.env.PAPERCLIP_AGENT_ID?.trim() || null,+ };+}++async function readBody(args, textFlag, fileFlag) {+ const direct = readStringFlag(args, textFlag);+ const file = readStringFlag(args, fileFlag);+ if (direct && file) throw new UsageError(`Use either --${textFlag} or --${fileFlag}, not both`);+ if (direct) return direct;+ if (!file) return null;+ if (file === "-") {+ return await new Promise((resolve, reject) => {+ let data = "";+ process.stdin.setEncoding("utf8");+ process.stdin.on("data", (chunk) => {+ data += chunk;+ });+ process.stdin.on("end", () => resolve(data));+ process.stdin.on("error", reject);+ });+ }+ return fs.readFile(file, "utf8");+}++async function apiFetch(config, path, options = {}) {+ const headers = {+ Authorization: `Bearer ${config.apiKey}`,+ Accept: "application/json",+ ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}),+ ...(options.mutating && config.runId ? { "X-Paperclip-Run-Id": config.runId } : {}),+ };+ const response = await fetch(`${config.apiBaseUrl}${path}`, {+ method: options.method ?? "GET",+ headers,+ body: options.body === undefined ? undefined : JSON.stringify(options.body),+ });+ const text = await response.text();+ let body = null;+ if (text) {+ try {+ body = JSON.parse(text);+ } catch {+ body = { error: text.slice(0, 1000) };+ }+ }+ if (!response.ok) throw new ApiError(response.status, body);+ return body;+}++async function resolveIdentity(config) {+ if (config.companyId && config.agentId) {+ return { companyId: config.companyId, agentId: config.agentId, agent: null };+ }+ const agent = await apiFetch(config, "/agents/me");+ const companyId = config.companyId || agent.companyId;+ const agentId = config.agentId || agent.id;+ if (!companyId || !agentId) throw new ApiError(500, { error: "Paperclip identity response did not include companyId and agent id" });+ return { companyId, agentId, agent };+}++function issueSummary(issue) {+ if (!issue || typeof issue !== "object") return issue;+ return {+ id: issue.id ?? null,+ identifier: issue.identifier ?? null,+ title: issue.title ?? null,+ status: issue.status ?? null,+ priority: issue.priority ?? null,+ assigneeAgentId: issue.assigneeAgentId ?? null,+ assigneeUserId: issue.assigneeUserId ?? null,+ projectId: issue.projectId ?? null,+ goalId: issue.goalId ?? null,+ parentId: issue.parentId ?? null,+ updatedAt: issue.updatedAt ?? null,+ };+}++function commentSummary(comment) {+ if (!comment || typeof comment !== "object") return comment;+ return {+ id: comment.id ?? null,+ issueId: comment.issueId ?? null,+ authorType: comment.authorType ?? null,+ authorAgentId: comment.authorAgentId ?? null,+ createdAt: comment.createdAt ?? null,+ };+}++function printJson(value) {+ process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);+}++function validateEnum(value, allowed, label) {+ if (!allowed.has(value)) {+ throw new UsageError(`Invalid ${label}: ${value}`);+ }+ return value;+}++function parseLimit(args) {+ const raw = readStringFlag(args, "limit");+ if (!raw) return 20;+ const value = Number.parseInt(raw, 10);+ if (!Number.isInteger(value) || value <= 0 || value > 100) {+ throw new UsageError("--limit must be an integer from 1 to 100");+ }+ return value;+}++async function listAssigned(config, args) {+ const identity = await resolveIdentity(config);+ const status = readStringFlag(args, "status") || "todo,in_progress,in_review,blocked";+ const limit = parseLimit(args);+ const issues = await apiFetch(config, "/agents/me/inbox-lite");+ const allowedStatuses = new Set(status.split(",").map((entry) => entry.trim()).filter(Boolean));+ const filteredIssues = Array.isArray(issues)+ ? issues.filter((issue) => !allowedStatuses.size || allowedStatuses.has(issue?.status)).slice(0, limit)+ : [];+ printJson({+ command: "list-assigned",+ companyId: identity.companyId,+ agentId: identity.agentId,+ count: filteredIssues.length,+ issues: filteredIssues.map(issueSummary),+ });+}++async function createTask(config, args) {+ const identity = await resolveIdentity(config);+ const title = requireStringFlag(args, "title");+ const description = await readBody(args, "description", "description-file");+ const unassigned = boolFlag(args, "unassigned");+ const assigneeRaw = readStringFlag(args, "assignee-agent-id");+ const assigneeAgentId = unassigned+ ? undefined+ : !assigneeRaw || assigneeRaw === "self"+ ? identity.agentId+ : assigneeRaw;+ if (assigneeAgentId !== undefined && !UUID_RE.test(assigneeAgentId)) {+ throw new UsageError("--assignee-agent-id must be a UUID, self, or omitted");+ }+ const priority = readStringFlag(args, "priority") ?? "medium";+ const workMode = readStringFlag(args, "work-mode") ?? "standard";+ validateEnum(priority, PRIORITIES, "priority");+ validateEnum(workMode, WORK_MODES, "work mode");+ const body = {+ title,+ description,+ priority,+ workMode,+ ...(assigneeAgentId !== undefined ? { assigneeAgentId } : {}),+ };+ for (const [flag, field] of [+ ["parent-id", "parentId"],+ ["goal-id", "goalId"],+ ["project-id", "projectId"],+ ]) {+ const value = readStringFlag(args, flag);+ if (value) body[field] = value;+ }+ const status = readStringFlag(args, "status");+ if (status) body.status = validateEnum(status, STATUSES, "status");++ const issue = await apiFetch(config, `/companies/${encodeURIComponent(identity.companyId)}/issues`, {+ method: "POST",+ mutating: true,+ body,+ });+ printJson({ command: "create-task", issue: issueSummary(issue) });+}++async function comment(config, args) {+ const issueRef = requireStringFlag(args, "issue");+ const bodyText = await readBody(args, "body", "body-file");+ if (!bodyText || bodyText.trim().length === 0) throw new UsageError("comment requires --body or --body-file");+ const commentBody = {+ body: bodyText,+ ...(boolFlag(args, "resume") ? { resume: true } : {}),+ ...(boolFlag(args, "reopen") ? { reopen: true } : {}),+ };+ const created = await apiFetch(config, `/issues/${encodeURIComponent(issueRef)}/comments`, {+ method: "POST",+ mutating: true,+ body: commentBody,+ });+ printJson({ command: "comment", issue: issueRef, comment: commentSummary(created) });+}++async function updateStatus(config, args) {+ const issueRef = requireStringFlag(args, "issue");+ const status = validateEnum(requireStringFlag(args, "status"), STATUSES, "status");+ const commentText = await readBody(args, "comment", "comment-file");+ const body = {+ status,+ ...(commentText && commentText.trim().length > 0 ? { comment: commentText } : {}),+ ...(boolFlag(args, "resume") ? { resume: true } : {}),+ ...(boolFlag(args, "reopen") ? { reopen: true } : {}),+ };+ const issue = await apiFetch(config, `/issues/${encodeURIComponent(issueRef)}`, {+ method: "PATCH",+ mutating: true,+ body,+ });+ printJson({ command: "update-status", issue: issueSummary(issue) });+}++async function main() {+ const args = parseArgs(process.argv.slice(2));+ const command = args._[0];+ if (!command || command === "help" || command === "--help" || boolFlag(args, "help")) {+ process.stdout.write(`${HELP}\n`);+ return;+ }+ const config = getConfig();+ if (command === "list-assigned") return listAssigned(config, args);+ if (command === "create-task") return createTask(config, args);+ if (command === "comment") return comment(config, args);+ if (command === "update-status") return updateStatus(config, args);+ throw new UsageError(`Unknown command: ${command}`);+}++main().catch((err) => {+ if (err instanceof UsageError) {+ process.stderr.write(`Usage error: ${err.message}\n\n${HELP}\n`);+ process.exitCode = 2;+ return;+ }+ if (err instanceof ApiError) {+ printJson({+ error: err.message,+ status: err.status,+ details: err.body?.details ?? null,+ });+ process.exitCode = 1;+ return;+ }+ process.stderr.write(`Unexpected error: ${err instanceof Error ? err.message : String(err)}\n`);+ process.exitCode = 1;+});diff --git a/packages/adapters/hermes/src/cli/format-event.ts b/packages/adapters/hermes/src/cli/format-event.tsnew file mode 100644index 0000000000..5f44bbeb4d--- /dev/null+++ b/packages/adapters/hermes/src/cli/format-event.ts@@ -0,0 +1,61 @@+/**+ * CLI output formatting for Hermes Agent adapter.+ *+ * Pretty-prints Hermes output lines in the terminal when running+ * Paperclip's CLI tools.+ */++import pc from "picocolors";++/**+ * Format a Hermes Agent stdout event for terminal display.+ *+ * @param raw Raw stdout line from Hermes+ * @param debug If true, show extra metadata with color coding+ */+export function printHermesStreamEvent(raw: string, debug: boolean): void {+ const line = raw.trim();+ if (!line) return;++ if (!debug) {+ console.log(line);+ return;+ }++ // Adapter log lines+ if (line.startsWith("[hermes]")) {+ console.log(pc.blue(line));+ return;+ }++ // Tool output (┊ prefix)+ if (line.startsWith("┊")) {+ console.log(pc.cyan(line));+ return;+ }++ // Thinking+ if (line.includes("💭") || line.startsWith("<thinking>")) {+ console.log(pc.dim(line));+ return;+ }++ // Errors+ if (+ line.startsWith("Error:") ||+ line.startsWith("ERROR:") ||+ line.startsWith("Traceback")+ ) {+ console.log(pc.red(line));+ return;+ }++ // Session info+ if (/session/i.test(line) && /id|saved|resumed/i.test(line)) {+ console.log(pc.green(line));+ return;+ }++ // Default: gray in debug mode+ console.log(pc.gray(line));+}diff --git a/packages/adapters/hermes/src/cli/index.ts b/packages/adapters/hermes/src/cli/index.tsnew file mode 100644index 0000000000..2177ef6627--- /dev/null+++ b/packages/adapters/hermes/src/cli/index.ts@@ -0,0 +1,5 @@+/**+ * CLI module exports — used by Paperclip's CLI for terminal formatting.+ */++export { printHermesStreamEvent } from "./format-event.js";diff --git a/packages/adapters/hermes/src/gateway/cli/format-event.ts b/packages/adapters/hermes/src/gateway/cli/format-event.tsnew file mode 100644index 0000000000..58705bc40a--- /dev/null+++ b/packages/adapters/hermes/src/gateway/cli/format-event.ts@@ -0,0 +1,13 @@+export function printHermesGatewayStreamEvent(line: string, debug: boolean): void {+ const trimmed = line.trim();+ if (!trimmed) return;+ if (trimmed.startsWith("[hermes-gateway:event]")) {+ console.log(trimmed);+ return;+ }+ if (trimmed.startsWith("[hermes-gateway]")) {+ console.log(trimmed);+ return;+ }+ if (debug) console.log(line);+}diff --git a/packages/adapters/hermes/src/gateway/cli/index.ts b/packages/adapters/hermes/src/gateway/cli/index.tsnew file mode 100644index 0000000000..673d48880d--- /dev/null+++ b/packages/adapters/hermes/src/gateway/cli/index.ts@@ -0,0 +1 @@+export { printHermesGatewayStreamEvent as formatStdoutEvent } from "./format-event.js";diff --git a/packages/adapters/hermes/src/gateway/index.ts b/packages/adapters/hermes/src/gateway/index.tsnew file mode 100644index 0000000000..dd89113df8--- /dev/null+++ b/packages/adapters/hermes/src/gateway/index.ts@@ -0,0 +1,72 @@+import type { AdapterSessionManagement, ServerAdapterModule } from "@paperclipai/adapter-utils";+import { ADAPTER_LABEL, ADAPTER_TYPE } from "./shared/constants.js";+import { execute, getConfigSchema, sessionCodec, testEnvironment } from "./server/index.js";++export const type = ADAPTER_TYPE;+export const label = ADAPTER_LABEL;+export const models: { id: string; label: string }[] = [];++const sessionManagement: AdapterSessionManagement = {+ supportsSessionResume: true,+ nativeContextManagement: "confirmed",+ defaultSessionCompaction: {+ enabled: true,+ maxSessionRuns: 0,+ maxRawInputTokens: 0,+ maxSessionAgeHours: 0,+ },+};++export const agentConfigurationDoc = `# hermes_gateway agent configuration++Adapter: hermes_gateway++Use when:+- Hermes Agent runs on another host or process that exposes the Hermes API server.+- Paperclip should create Hermes runs through POST /v1/runs and observe them through SSE events.+- You need remote Hermes session continuity with X-Hermes-Session-Key.++Don't use when:+- Hermes should run as a local child process on the Paperclip host; use hermes_local instead.+- The Hermes API server is not enabled or is only reachable over an unsafe public HTTP endpoint.+- You need Hermes-originated Paperclip task creation only; that is a Paperclip skill/API bridge, not this wake adapter.++Required fields:+- apiBaseUrl (string): Hermes API server base URL, for example http://127.0.0.1:8642.+- apiKey (string): Hermes API_SERVER_KEY. Sent as Authorization: Bearer <apiKey>.++Optional fields:+- headers (object or JSON string): extra noncritical headers. Authorization, Content-Type, Accept, Idempotency-Key, and X-Hermes-Session-Key are generated by the adapter.+- paperclipApiUrl (string): Paperclip API URL reachable from the Hermes host. This is not a credential.+- sessionKeyStrategy (issue | agent | run | none): defaults to issue.+- timeoutSec (number): defaults to 120.+- eventReconnectMs (number): defaults to 2000.+- instructions (string): stable Hermes instructions sent separately from wake input.++Runtime mapping:+- Creates runs with POST /v1/runs.+- Sends Idempotency-Key equal to the Paperclip run id for correlation only; Hermes v0.16.0 did not dedupe duplicate creates.+- Streams GET /v1/runs/{run_id}/events and polls GET /v1/runs/{run_id} as fallback.+- Calls POST /v1/runs/{run_id}/stop on timeout.++Security guidance:+- Prefer HTTPS or a private overlay network for non-loopback hosts.+- Do not put Hermes apiKey or Paperclip bearer tokens in prompts, comments, logs, or result JSON.+- Keep the default issue-scoped session strategy unless shared agent memory is intentional.+`;++export function createServerAdapter(): ServerAdapterModule {+ return {+ type,+ execute,+ testEnvironment,+ sessionCodec,+ sessionManagement,+ models,+ supportsLocalAgentJwt: false,+ supportsInstructionsBundle: false,+ requiresMaterializedRuntimeSkills: false,+ agentConfigurationDoc,+ getConfigSchema,+ };+}diff --git a/packages/adapters/hermes/src/gateway/server/config-schema.ts b/packages/adapters/hermes/src/gateway/server/config-schema.tsnew file mode 100644index 0000000000..ad27054d23--- /dev/null+++ b/packages/adapters/hermes/src/gateway/server/config-schema.ts@@ -0,0 +1,76 @@+import type { AdapterConfigSchema } from "@paperclipai/adapter-utils";+import { DEFAULT_EVENT_RECONNECT_MS, DEFAULT_TIMEOUT_SEC } from "../shared/constants.js";+import { INSECURE_REMOTE_HTTP_ESCAPE_HATCH } from "./transport-security.js";++export function getConfigSchema(): AdapterConfigSchema {+ return {+ fields: [+ {+ key: "apiBaseUrl",+ label: "API base URL",+ type: "text",+ required: true,+ hint: "Hermes API server base URL, such as http://127.0.0.1:8642 or a private HTTPS URL.",+ },+ {+ key: "apiKey",+ label: "API key",+ type: "text",+ required: true,+ hint: "Hermes API_SERVER_KEY. Stored as a Paperclip secret reference.",+ meta: { secret: true },+ },+ {+ key: INSECURE_REMOTE_HTTP_ESCAPE_HATCH,+ label: "Dangerously allow remote HTTP",+ type: "toggle",+ default: false,+ hint: "Unsafe dev-only escape hatch. Remote Hermes gateways should use HTTPS; loopback HTTP remains allowed.",+ },+ {+ key: "sessionKeyStrategy",+ label: "Session key strategy",+ type: "select",+ default: "issue",+ options: [+ { value: "issue", label: "Issue scoped" },+ { value: "agent", label: "Agent scoped" },+ { value: "run", label: "Run scoped" },+ { value: "none", label: "None" },+ ],+ hint: "Controls X-Hermes-Session-Key. Issue scoped prevents cross-task memory bleed by default.",+ },+ {+ key: "timeoutSec",+ label: "Timeout seconds",+ type: "number",+ default: DEFAULT_TIMEOUT_SEC,+ },+ {+ key: "eventReconnectMs",+ label: "Event reconnect ms",+ type: "number",+ default: DEFAULT_EVENT_RECONNECT_MS,+ hint: "Delay before reconnecting the Hermes SSE events stream after a nonterminal disconnect.",+ },+ {+ key: "paperclipApiUrl",+ label: "Paperclip API URL",+ type: "text",+ hint: "Optional Paperclip API URL reachable by the remote Hermes host. This is not a credential.",+ },+ {+ key: "headers",+ label: "Extra headers",+ type: "textarea",+ hint: "Optional JSON object of extra nonsecret headers. Security-critical headers are generated by the adapter.",+ },+ {+ key: "instructions",+ label: "Instructions",+ type: "textarea",+ hint: "Optional stable Hermes instructions sent separately from the wake input.",+ },+ ],+ };+}diff --git a/packages/adapters/hermes/src/gateway/server/execute.test.ts b/packages/adapters/hermes/src/gateway/server/execute.test.tsnew file mode 100644index 0000000000..de3c165756--- /dev/null+++ b/packages/adapters/hermes/src/gateway/server/execute.test.ts@@ -0,0 +1,417 @@+import { describe, expect, it, vi, afterEach } from "vitest";+import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";+import { execute, mapFinalResultForTest, parseSseFramesForTest, resolveSessionKey } from "./execute.js";+import { testEnvironment } from "./test.js";++function makeCtx(config: Record<string, unknown>): AdapterExecutionContext {+ return {+ runId: "pc-run-1",+ agent: {+ id: "agent-1",+ companyId: "company-1",+ name: "Hermes",+ adapterType: "hermes_gateway",+ adapterConfig: config,+ },+ runtime: {+ sessionId: null,+ sessionParams: null,+ sessionDisplayId: null,+ taskKey: null,+ },+ config,+ context: {+ issueId: "issue-1",+ wakeReason: "manual",+ paperclipWake: {+ issue: { identifier: "PAP-1", title: "Do the thing" },+ },+ },+ onLog: vi.fn(async () => undefined),+ onMeta: vi.fn(async () => undefined),+ };+}++function sseStream(text: string): ReadableStream<Uint8Array> {+ return new ReadableStream<Uint8Array>({+ start(controller) {+ controller.enqueue(new TextEncoder().encode(text));+ controller.close();+ },+ });+}++afterEach(() => {+ vi.restoreAllMocks();+});++describe("resolveSessionKey", () => {+ it("derives issue-scoped session keys by default", () => {+ expect(+ resolveSessionKey({+ strategy: "issue",+ companyId: "company-1",+ agentId: "agent-1",+ runId: "run-1",+ issueId: "issue-1",+ }),+ ).toBe("paperclip:company:company-1:agent:agent-1:issue:issue-1");+ });++ it("omits the session key for none strategy", () => {+ expect(+ resolveSessionKey({+ strategy: "none",+ companyId: "company-1",+ agentId: "agent-1",+ runId: "run-1",+ issueId: "issue-1",+ }),+ ).toBeNull();+ });+});++describe("parseSseFramesForTest", () => {+ it("parses event and data lines while preserving partial frames", () => {+ const parsed = parseSseFramesForTest("event: message.delta\ndata: {\"delta\":\"hi\"}\n\n:data\ndata: later");+ expect(parsed.frames).toEqual([{ event: "message.delta", data: "{\"delta\":\"hi\"}" }]);+ expect(parsed.rest).toBe(":data\ndata: later");+ });+});++describe("execute", () => {+ it("rejects remote plain HTTP unless the unsafe dev escape hatch is enabled", async () => {+ const fetchMock = vi.fn(async () => new Response(JSON.stringify({ run_id: "unexpected" }), { status: 200 }));+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(makeCtx({+ apiBaseUrl: "http://192.168.1.25:8642",+ apiKey: "secret-key",+ }));++ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("hermes_gateway_plain_http_remote_denied");+ expect(fetchMock).not.toHaveBeenCalled();+ });++ it("constructs POST /v1/runs with auth, idempotency, and Hermes session headers", async () => {+ const fetchMock = vi.fn(async (input: RequestInfo | URL) => {+ const url = String(input);+ if (url.endsWith("/v1/runs")) {+ return new Response(JSON.stringify({ run_id: "run-hermes-1", status: "started" }), { status: 200 });+ }+ if (url.endsWith("/events")) {+ return new Response(+ sseStream(+ [+ "event: message.delta",+ "data: {\"delta\":\"done\"}",+ "",+ "event: run.completed",+ "data: {\"status\":\"completed\",\"output\":\"done\",\"session_id\":\"session-1\",\"usage\":{\"input_tokens\":3,\"output_tokens\":2},\"model\":\"hermes-agent\"}",+ "",+ ].join("\n"),+ ),+ { status: 200, headers: { "content-type": "text/event-stream" } },+ );+ }+ return new Response(JSON.stringify({ status: "completed", output: "done" }), { status: 200 });+ });+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(makeCtx({+ apiBaseUrl: "http://127.0.0.1:8642",+ apiKey: "secret-key",+ timeoutSec: 5,+ }));++ expect(result.exitCode).toBe(0);+ expect(result.summary).toBe("done");+ expect(result.usage).toEqual({ inputTokens: 3, outputTokens: 2 });++ const calls = fetchMock.mock.calls as Array<[RequestInfo | URL, RequestInit?]>;+ const createCall = calls.find(([input]) => String(input).endsWith("/v1/runs"));+ expect(createCall).toBeTruthy();+ const init = createCall?.[1] as RequestInit;+ expect(init.headers).toMatchObject({+ Authorization: "Bearer secret-key",+ "Content-Type": "application/json",+ "Idempotency-Key": "pc-run-1",+ "X-Hermes-Session-Key": "paperclip:company:company-1:agent:agent-1:issue:issue-1",+ });+ const body = JSON.parse(String(init.body));+ expect(body.input).toContain("Do the thing");+ expect(body.session_id).toBe("paperclip:company:company-1:agent:agent-1:issue:issue-1");+ });++ it("redacts echoed auth material from stream logs and summaries", async () => {+ const ctx = makeCtx({+ apiBaseUrl: "http://127.0.0.1:8642",+ apiKey: "secret-key",+ timeoutSec: 5,+ });+ const fetchMock = vi.fn(async (input: RequestInfo | URL) => {+ const url = String(input);+ if (url.endsWith("/v1/runs")) {+ return new Response(JSON.stringify({ run_id: "run-hermes-1", status: "started" }), { status: 200 });+ }+ if (url.endsWith("/events")) {+ return new Response(+ sseStream(+ [+ "event: message.delta",+ "data: {\"delta\":\"Authorization: Bearer secret-key\\nX-Hermes-Session-Key: paperclip:company:company-1:agent:agent-1:issue:issue-1\"}",+ "",+ "event: run.completed",+ "data: {\"status\":\"completed\",\"output\":\"Authorization: Bearer secret-key\\nraw key secret-key\\nX-Hermes-Session-Key: paperclip:company:company-1:agent:agent-1:issue:issue-1\"}",+ "",+ ].join("\n"),+ ),+ { status: 200, headers: { "content-type": "text/event-stream" } },+ );+ }+ return new Response(JSON.stringify({ status: "completed" }), { status: 200 });+ });+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(ctx);+ const logText = (ctx.onLog as ReturnType<typeof vi.fn>).mock.calls.map(([, line]) => String(line)).join("\n");++ expect(result.exitCode).toBe(0);+ expect(result.summary).toContain("Bearer [redacted]");+ expect(result.summary).toContain("raw key [redacted len=10]");+ expect(result.summary).toContain("X-Hermes-Session-Key: [redacted]");+ expect(result.summary).not.toContain("secret-key");+ expect(result.summary).not.toContain("paperclip:company:company-1:agent:agent-1:issue:issue-1");+ expect(result.resultJson?.output).toBe(result.summary);+ expect(logText).toContain("Bearer [redacted]");+ expect(logText).toContain("X-Hermes-Session-Key: [redacted]");+ expect(logText).not.toContain("secret-key");+ expect(logText).not.toContain("paperclip:company:company-1:agent:agent-1:issue:issue-1");+ });++ it("redacts agent-scoped Paperclip session keys from logs and public result metadata", async () => {+ const ctx = makeCtx({+ apiBaseUrl: "http://127.0.0.1:8642",+ apiKey: "secret-key",+ sessionKeyStrategy: "agent",+ timeoutSec: 5,+ });+ const agentSessionKey = "paperclip:company:company-1:agent:agent-1";+ const fetchMock = vi.fn(async (input: RequestInfo | URL) => {+ const url = String(input);+ if (url.endsWith("/v1/runs")) {+ return new Response(JSON.stringify({ run_id: "run-hermes-1", status: "started" }), { status: 200 });+ }+ if (url.endsWith("/events")) {+ return new Response(+ sseStream(+ [+ "event: message.delta",+ `data: {"delta":"session ${agentSessionKey}"}`,+ "",+ "event: run.completed",+ `data: {"status":"completed","output":"session ${agentSessionKey}","session_id":"${agentSessionKey}"}`,+ "",+ ].join("\n"),+ ),+ { status: 200, headers: { "content-type": "text/event-stream" } },+ );+ }+ return new Response(JSON.stringify({ status: "completed" }), { status: 200 });+ });+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(ctx);+ const logText = (ctx.onLog as ReturnType<typeof vi.fn>).mock.calls.map(([, line]) => String(line)).join("\n");++ expect(result.exitCode).toBe(0);+ expect(result.summary).toBe("session [redacted-session-key]");+ expect(result.sessionId).toBe("[redacted-session-key]");+ expect(result.sessionDisplayId).toBe("[redacted-session-key]");+ expect(result.resultJson?.session_id).toBe("[redacted-session-key]");+ expect(result.sessionParams).toEqual({+ hermesRunId: "run-hermes-1",+ strategy: "agent",+ });+ expect(logText).toContain("[redacted-session-key]");+ expect(logText).not.toContain(agentSessionKey);+ });++ it("falls back to polling when SSE is unavailable", async () => {+ const fetchMock = vi.fn(async (input: RequestInfo | URL) => {+ const url = String(input);+ if (url.endsWith("/v1/runs")) {+ return new Response(JSON.stringify({ run_id: "run-hermes-1", status: "started" }), { status: 200 });+ }+ if (url.endsWith("/events")) {+ return new Response("no stream", { status: 503 });+ }+ return new Response(JSON.stringify({+ status: "completed",+ output: "polled done",+ session_id: "session-polled",+ }), { status: 200 });+ });+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(makeCtx({+ apiBaseUrl: "http://127.0.0.1:8642",+ apiKey: "secret-key",+ timeoutSec: 5,+ pollIntervalMs: 250,+ }));++ expect(result.exitCode).toBe(0);+ expect(result.summary).toBe("polled done");+ expect(fetchMock.mock.calls.some(([input]) => String(input).endsWith("/v1/runs/run-hermes-1"))).toBe(true);+ });++ it("maps HTTP auth failures", async () => {+ vi.stubGlobal("fetch", vi.fn(async () => new Response(JSON.stringify({ error: "bad key" }), { status: 401 })));+ const result = await execute(makeCtx({+ apiBaseUrl: "http://127.0.0.1:8642",+ apiKey: "secret-key",+ }));+ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("hermes_gateway_auth_failed");+ });++ it("redacts echoed auth material from HTTP error payloads", async () => {+ vi.stubGlobal(+ "fetch",+ vi.fn(async () =>+ new Response(+ JSON.stringify({+ message: "Authorization rejected: Bearer secret-key raw secret-key",+ detail: "X-Hermes-Session-Key: paperclip:company:company-1:agent:agent-1:issue:issue-1",+ nested: {+ note: "session paperclip:company:company-1:agent:agent-1",+ },+ }),+ { status: 401 },+ )),+ );++ const result = await execute(makeCtx({+ apiBaseUrl: "http://127.0.0.1:8642",+ apiKey: "secret-key",+ }));++ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("hermes_gateway_auth_failed");+ expect(result.errorMeta?.body).toEqual({+ message: "Authorization rejected: Bearer [redacted] raw [redacted len=10]",+ detail: "X-Hermes-Session-Key: [redacted]",+ nested: {+ note: "session [redacted-session-key]",+ },+ });+ expect(result.errorMessage).not.toContain("secret-key");+ expect(result.errorMessage).not.toContain("paperclip:company:company-1:agent:agent-1:issue:issue-1");+ });++ it("calls stop on timeout", async () => {+ const fetchMock = vi.fn(async (input: RequestInfo | URL, init?: RequestInit) => {+ const url = String(input);+ if (url.endsWith("/v1/runs")) {+ return new Response(JSON.stringify({ run_id: "run-slow", status: "started" }), { status: 200 });+ }+ if (url.endsWith("/events")) {+ return new Promise<Response>(() => {});+ }+ if (url.endsWith("/stop")) {+ return new Response(JSON.stringify({ status: "stopping" }), { status: 200 });+ }+ if (init?.method === "GET") {+ return new Response(JSON.stringify({ status: "cancelled", last_event: "run.cancelled" }), { status: 200 });+ }+ return new Response(JSON.stringify({ status: "running" }), { status: 200 });+ });+ vi.stubGlobal("fetch", fetchMock);++ const result = await execute(makeCtx({+ apiBaseUrl: "http://127.0.0.1:8642",+ apiKey: "secret-key",+ timeoutSec: 0.001,+ }));++ expect(result.timedOut).toBe(true);+ expect(result.errorCode).toBe("hermes_gateway_timeout");+ expect(fetchMock.mock.calls.some(([input]) => String(input).endsWith("/stop"))).toBe(true);+ });+});++describe("testEnvironment", () => {+ it("fails remote plain HTTP before probing health", async () => {+ const fetchMock = vi.fn(async () => new Response("{}", { status: 200 }));+ vi.stubGlobal("fetch", fetchMock);++ const result = await testEnvironment({+ companyId: "company-1",+ adapterType: "hermes_gateway",+ config: {+ apiBaseUrl: "http://hermes.example:8642",+ apiKey: "secret-key",+ },+ });++ expect(result.status).toBe("fail");+ expect(result.checks).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ code: "hermes_gateway_plain_http_remote_denied",+ level: "error",+ }),+ ]),+ );+ expect(fetchMock).not.toHaveBeenCalled();+ });++ it("allows remote plain HTTP only with the unsafe dev escape hatch", async () => {+ const fetchMock = vi.fn(async () => new Response("{}", { status: 200 }));+ vi.stubGlobal("fetch", fetchMock);++ const result = await testEnvironment({+ companyId: "company-1",+ adapterType: "hermes_gateway",+ config: {+ apiBaseUrl: "http://hermes.example:8642",+ apiKey: "secret-key",+ dangerouslyAllowInsecureRemoteHttp: true,+ },+ });++ expect(result.status).toBe("warn");+ expect(result.checks).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ code: "hermes_gateway_plain_http_remote_unsafe_allowed",+ level: "warn",+ }),+ expect.objectContaining({+ code: "hermes_gateway_health_ok",+ }),+ ]),+ );+ expect(fetchMock).toHaveBeenCalled();+ });+});++describe("mapFinalResultForTest", () => {+ it("maps failed statuses into adapter errors", () => {+ const result = mapFinalResultForTest({+ terminal: {+ runId: "run-1",+ status: "failed",+ payload: { status: "failed", error: "boom" },+ },+ outputChunks: [],+ sessionKey: "session-key",+ strategy: "issue",+ });+ expect(result.exitCode).toBe(1);+ expect(result.errorCode).toBe("hermes_gateway_run_failed");+ expect(result.errorMessage).toBe("boom");+ });+});diff --git a/packages/adapters/hermes/src/gateway/server/execute.ts b/packages/adapters/hermes/src/gateway/server/execute.tsnew file mode 100644index 0000000000..f28ccea4fe--- /dev/null+++ b/packages/adapters/hermes/src/gateway/server/execute.ts@@ -0,0 +1,914 @@+import type {+ AdapterExecutionContext,+ AdapterExecutionResult,+ UsageSummary,+} from "@paperclipai/adapter-utils";+import {+ asNumber,+ asString,+ parseObject,+ readPaperclipIssueWorkModeFromContext,+ renderPaperclipWakePrompt,+ stringifyPaperclipWakePayload,+} from "@paperclipai/adapter-utils/server-utils";+import {+ ADAPTER_TYPE,+ DEFAULT_EVENT_RECONNECT_MS,+ DEFAULT_POLL_INTERVAL_MS,+ DEFAULT_TIMEOUT_SEC,+ STOP_GRACE_MS,+} from "../shared/constants.js";+import {+ allowsInsecureRemoteHttp,+ isRemotePlainHttp,+ remotePlainHttpDeniedMessage,+} from "./transport-security.js";++type SessionKeyStrategy = "issue" | "agent" | "run" | "none";++type SseFrame = {+ event: string | null;+ data: string;+};++type HermesHttpError = Error & {+ status?: number;+ code?: string;+ retryNotBefore?: string | null;+ body?: unknown;+};++type TerminalState = {+ runId: string;+ status: string;+ eventName?: string | null;+ payload?: Record<string, unknown> | null;+ output?: string | null;+};++type ExecutionState = {+ runId: string;+ outputChunks: string[];+ lastEventName: string | null;+ terminal: TerminalState | null;+ resolveTerminal: (state: TerminalState) => void;+ terminalPromise: Promise<TerminalState>;+};++type TextRedactor = (value: string) => string;++const CRITICAL_HEADERS = new Set([+ "authorization",+ "content-type",+ "accept",+ "idempotency-key",+ "x-hermes-session-key",+]);++const SENSITIVE_KEY_PATTERN =+ /(^|[_-])(auth|authorization|token|secret|password|api[_-]?key|private[_-]?key)([_-]|$)/i;+const BEARER_TOKEN_PATTERN = /Bearer\s+\S+/gi;+const HERMES_SESSION_KEY_HEADER_PATTERN = /(X-Hermes-Session-Key\s*[:=]\s*)([^\s,;]+)/gi;+const PAPERCLIP_SESSION_KEY_PATTERN =+ /\bpaperclip:(?:company:[A-Za-z0-9-]+:agent:[A-Za-z0-9-]+(?::(?:issue|run):[A-Za-z0-9-]+)?|run:[A-Za-z0-9-]+)\b/gi;++const TERMINAL_STATUSES = new Set([+ "completed",+ "failed",+ "error",+ "cancelled",+ "canceled",+ "stopped",+ "interrupted",+]);++const FAILURE_STATUSES = new Set(["failed", "error"]);+const CANCELLED_STATUSES = new Set(["cancelled", "canceled", "stopped", "interrupted"]);++function asRecord(value: unknown): Record<string, unknown> | null {+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;+ return value as Record<string, unknown>;+}++function nonEmpty(value: unknown): string | null {+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;+}++function parseNonNegativeNumber(value: unknown, fallback: number): number {+ const parsed = typeof value === "number"+ ? value+ : typeof value === "string"+ ? Number.parseFloat(value)+ : Number.NaN;+ if (!Number.isFinite(parsed)) return fallback;+ return Math.max(0, parsed);+}++function clamp(value: number, min: number, max: number): number {+ return Math.min(max, Math.max(min, value));+}++function normalizeSessionKeyStrategy(value: unknown): SessionKeyStrategy {+ const raw = asString(value, "issue").trim().toLowerCase();+ if (raw === "agent" || raw === "run" || raw === "none") return raw;+ return "issue";+}++function normalizeBaseUrl(value: string): URL | null {+ try {+ const url = new URL(value);+ if (url.protocol !== "http:" && url.protocol !== "https:") return null;+ url.pathname = url.pathname.replace(/\/+$/, "");+ url.search = "";+ url.hash = "";+ return url;+ } catch {+ return null;+ }+}++function apiUrl(baseUrl: URL, path: string): string {+ const base = baseUrl.toString().replace(/\/+$/, "");+ return `${base}${path}`;+}++function issueIdFromContext(ctx: AdapterExecutionContext): string | null {+ return nonEmpty(ctx.context.taskId) ?? nonEmpty(ctx.context.issueId);+}++export function resolveSessionKey(input: {+ strategy: SessionKeyStrategy;+ companyId: string;+ agentId: string;+ runId: string;+ issueId: string | null;+}): string | null {+ if (input.strategy === "none") return null;+ if (input.strategy === "agent") {+ return `paperclip:company:${input.companyId}:agent:${input.agentId}`;+ }+ if (input.strategy === "run") {+ return `paperclip:run:${input.runId}`;+ }+ const issuePart = input.issueId ? `issue:${input.issueId}` : `run:${input.runId}`;+ return `paperclip:company:${input.companyId}:agent:${input.agentId}:${issuePart}`;+}++function stringifyForLog(value: unknown, maxChars = 4_000): string {+ const text = JSON.stringify(value);+ return text.length <= maxChars ? text : `${text.slice(0, maxChars)}... [truncated ${text.length - maxChars} chars]`;+}++function sanitizeSensitiveText(value: string): string {+ return value+ .replace(BEARER_TOKEN_PATTERN, "Bearer [redacted]")+ .replace(HERMES_SESSION_KEY_HEADER_PATTERN, "$1[redacted]")+ .replace(PAPERCLIP_SESSION_KEY_PATTERN, "[redacted-session-key]");+}++function escapeRegExp(value: string): string {+ return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");+}++function createTextRedactor(secrets: Array<string | null | undefined>): TextRedactor {+ const exactSecrets = [...new Set(secrets.filter((secret): secret is string => typeof secret === "string" && secret.length >= 4))]+ .sort((a, b) => b.length - a.length)+ .map((secret) => ({+ secret,+ regex: new RegExp(escapeRegExp(secret), "g"),+ }));++ return (value: string) => {+ let result = sanitizeSensitiveText(value);+ for (const entry of exactSecrets) {+ result = result.replace(entry.regex, `[redacted len=${entry.secret.length}]`);+ }+ return result;+ };+}++function redactForLog(value: unknown, keyPath: string[] = [], depth = 0, redactText: TextRedactor = sanitizeSensitiveText): unknown {+ const key = keyPath[keyPath.length - 1] ?? "";+ if (typeof value === "string") {+ if (SENSITIVE_KEY_PATTERN.test(key)) return `[redacted len=${value.length}]`;+ const sanitized = redactText(value);+ return sanitized.length > 500+ ? `${sanitized.slice(0, 500)}... [truncated ${sanitized.length - 500} chars]`+ : sanitized;+ }+ if (value == null || typeof value === "number" || typeof value === "boolean") return value;+ if (Array.isArray(value)) {+ if (depth > 5) return "[array-truncated]";+ return value.slice(0, 40).map((entry, index) => redactForLog(entry, [...keyPath, String(index)], depth + 1, redactText));+ }+ if (typeof value === "object") {+ if (depth > 5) return "[object-truncated]";+ const out: Record<string, unknown> = {};+ for (const [entryKey, entryValue] of Object.entries(value as Record<string, unknown>).slice(0, 80)) {+ out[entryKey] = redactForLog(entryValue, [...keyPath, entryKey], depth + 1, redactText);+ }+ return out;+ }+ return redactText(String(value));+}++function parseHeaders(value: unknown): Record<string, string> {+ const source =+ typeof value === "string" && value.trim().length > 0+ ? (() => {+ try {+ return JSON.parse(value);+ } catch {+ return {};+ }+ })()+ : value;+ const parsed = parseObject(source);+ const headers: Record<string, string> = {};+ for (const [key, entry] of Object.entries(parsed)) {+ const normalized = key.trim();+ if (!normalized || CRITICAL_HEADERS.has(normalized.toLowerCase())) continue;+ if (typeof entry === "string") headers[normalized] = entry;+ }+ return headers;+}++function buildHeaders(input: {+ apiKey: string;+ sessionKey: string | null;+ runId: string;+ extraHeaders: Record<string, string>;+ accept: string;+ contentType?: string;+}): Record<string, string> {+ return {+ ...input.extraHeaders,+ Authorization: `Bearer ${input.apiKey}`,+ Accept: input.accept,+ ...(input.contentType ? { "Content-Type": input.contentType } : {}),+ "Idempotency-Key": input.runId,+ ...(input.sessionKey ? { "X-Hermes-Session-Key": input.sessionKey } : {}),+ };+}++function buildInput(ctx: AdapterExecutionContext, paperclipApiUrl: string | null): string {+ const wakePrompt = renderPaperclipWakePrompt(ctx.context.paperclipWake);+ const wakePayloadJson = stringifyPaperclipWakePayload(ctx.context.paperclipWake);+ const taskMarkdown = nonEmpty(ctx.context.paperclipTaskMarkdown);+ const sessionHandoff = nonEmpty(ctx.context.paperclipSessionHandoffMarkdown);+ const issueWorkMode = readPaperclipIssueWorkModeFromContext(ctx.context);+ const lines = [+ `You are ${ctx.agent.name}, an AI agent employee in a Paperclip-managed company.`,+ "",+ "Paperclip runtime identity:",+ `- Agent ID: ${ctx.agent.id}`,+ `- Company ID: ${ctx.agent.companyId}`,+ `- Run ID: ${ctx.runId}`,+ ...(paperclipApiUrl ? [`- Paperclip API URL: ${paperclipApiUrl}`] : []),+ ...(issueWorkMode ? [`- Issue work mode: ${issueWorkMode}`] : []),+ "",+ "Execution contract:",+ "- Take concrete action in this run when the task is actionable.",+ "- Do not stop at a plan unless the issue asks for planning only.",+ "- Leave durable progress and update the issue to a clear final disposition.",+ "- Use X-Paperclip-Run-Id on mutating Paperclip API requests when a Paperclip API key is available.",+ "",+ wakePrompt,+ ...(sessionHandoff ? ["", sessionHandoff] : []),+ ...(taskMarkdown ? ["", taskMarkdown] : []),+ ...(wakePayloadJson+ ? [+ "",+ "Structured wake payload JSON:",+ "```json",+ wakePayloadJson,+ "```",+ ]+ : []),+ ];+ return lines.filter((line) => line !== null && line !== undefined).join("\n").trim();+}++function buildRunBody(ctx: AdapterExecutionContext, sessionKey: string | null): Record<string, unknown> {+ const paperclipApiUrl = nonEmpty(ctx.config.paperclipApiUrl);+ const payloadTemplate = parseObject(ctx.config.payloadTemplate);+ const input = nonEmpty(payloadTemplate.input) ?? buildInput(ctx, paperclipApiUrl);+ const instructions =+ nonEmpty(ctx.config.instructions) ??+ nonEmpty(payloadTemplate.instructions) ??+ "Follow the Paperclip wake instructions exactly. Do not expose secrets in logs, comments, or final output.";+ return {+ ...payloadTemplate,+ input,+ instructions,+ ...(sessionKey ? { session_id: sessionKey } : {}),+ };+}++async function readResponseJson(response: Response): Promise<unknown> {+ const text = await response.text();+ if (!text.trim()) return null;+ try {+ return JSON.parse(text);+ } catch {+ return { text };+ }+}++function classifyHttpError(status: number): { code: string; family: AdapterExecutionResult["errorFamily"] | null } {+ if (status === 401 || status === 403) return { code: "hermes_gateway_auth_failed", family: null };+ if (status === 404) return { code: "hermes_gateway_runs_unsupported", family: null };+ if (status === 429) return { code: "hermes_gateway_rate_limited", family: "transient_upstream" };+ if (status >= 500) return { code: "hermes_gateway_upstream_error", family: "transient_upstream" };+ return { code: "hermes_gateway_protocol_error", family: null };+}++async function fetchJson(input: RequestInfo | URL, init: RequestInit): Promise<unknown> {+ let response: Response;+ try {+ response = await fetch(input, init);+ } catch (err) {+ const message = err instanceof Error ? err.message : String(err);+ const fetchErr = new Error(`Hermes gateway request failed: ${message}`) as HermesHttpError;+ fetchErr.code = "hermes_gateway_connect_failed";+ throw fetchErr;+ }+ const body = await readResponseJson(response);+ if (!response.ok) {+ const classified = classifyHttpError(response.status);+ const err = new Error(`Hermes gateway HTTP ${response.status}`) as HermesHttpError;+ err.status = response.status;+ err.code = classified.code;+ err.retryNotBefore = response.headers.get("retry-after");+ err.body = body;+ throw err;+ }+ return body;+}++function extractRunId(value: unknown): string | null {+ const record = asRecord(value);+ return nonEmpty(record?.run_id) ?? nonEmpty(record?.runId) ?? nonEmpty(record?.id);+}++function eventNameFromData(data: unknown, fallback: string | null): string | null {+ const record = asRecord(data);+ return nonEmpty(record?.event) ?? nonEmpty(record?.type) ?? fallback;+}++function parseJsonData(data: string): unknown {+ try {+ return JSON.parse(data);+ } catch {+ return { text: data };+ }+}++export function parseSseFramesForTest(buffer: string): { frames: SseFrame[]; rest: string } {+ const normalized = buffer.replace(/\r\n/g, "\n");+ const frames: SseFrame[] = [];+ let offset = 0;+ while (true) {+ const idx = normalized.indexOf("\n\n", offset);+ if (idx < 0) break;+ const rawFrame = normalized.slice(offset, idx);+ offset = idx + 2;+ let event: string | null = null;+ const dataLines: string[] = [];+ for (const line of rawFrame.split("\n")) {+ if (!line || line.startsWith(":")) continue;+ if (line.startsWith("event:")) {+ event = line.slice("event:".length).trim();+ } else if (line.startsWith("data:")) {+ dataLines.push(line.slice("data:".length).trimStart());+ }+ }+ if (dataLines.length > 0) frames.push({ event, data: dataLines.join("\n") });+ }+ return { frames, rest: normalized.slice(offset) };+}++function createExecutionState(runId: string): ExecutionState {+ let resolveTerminal!: (state: TerminalState) => void;+ const terminalPromise = new Promise<TerminalState>((resolve) => {+ resolveTerminal = resolve;+ });+ return {+ runId,+ outputChunks: [],+ lastEventName: null,+ terminal: null,+ resolveTerminal,+ terminalPromise,+ };+}++function markTerminal(state: ExecutionState, terminal: TerminalState): void {+ if (state.terminal) return;+ state.terminal = terminal;+ state.resolveTerminal(terminal);+}++function extractStatus(value: unknown): string | null {+ const record = asRecord(value);+ return nonEmpty(record?.status)?.toLowerCase() ?? null;+}++function extractOutput(value: unknown): string | null {+ const record = asRecord(value);+ if (!record) return null;+ const direct =+ nonEmpty(record.output) ??+ nonEmpty(record.result) ??+ nonEmpty(record.text) ??+ nonEmpty(record.summary) ??+ nonEmpty(record.message);+ if (direct) return direct;+ const nested = asRecord(record.data) ?? asRecord(record.payload);+ return nested ? extractOutput(nested) : null;+}++async function handleEvent(+ ctx: AdapterExecutionContext,+ state: ExecutionState,+ frame: SseFrame,+ redactText: TextRedactor = sanitizeSensitiveText,+): Promise<void> {+ const parsed = parseJsonData(frame.data);+ const record = asRecord(parsed);+ const eventName = eventNameFromData(parsed, frame.event);+ state.lastEventName = eventName;+ await ctx.onLog(+ "stdout",+ `[hermes-gateway:event] run=${state.runId} event=${eventName ?? "message"} data=${stringifyForLog(redactForLog(parsed, [], 0, redactText), 8_000)}\n`,+ );++ const delta = nonEmpty(record?.delta) ?? nonEmpty(record?.text_delta);+ if (eventName === "message.delta" && delta) {+ const sanitizedDelta = redactText(delta);+ state.outputChunks.push(sanitizedDelta);+ await ctx.onLog("stdout", sanitizedDelta);+ }++ const status = extractStatus(parsed) ?? (eventName?.startsWith("run.") ? eventName.slice(4) : null);+ if (status && TERMINAL_STATUSES.has(status)) {+ markTerminal(state, {+ runId: state.runId,+ status,+ eventName,+ payload: record,+ output: extractOutput(parsed),+ });+ }+}++async function delay(ms: number, signal: AbortSignal): Promise<void> {+ if (signal.aborted) return;+ await new Promise<void>((resolve) => {+ const timer = setTimeout(resolve, ms);+ signal.addEventListener(+ "abort",+ () => {+ clearTimeout(timer);+ resolve();+ },+ { once: true },+ );+ });+}++async function pollStatus(input: {+ ctx: AdapterExecutionContext;+ baseUrl: URL;+ headers: Record<string, string>;+ state: ExecutionState;+ signal: AbortSignal;+ intervalMs: number;+ redactText?: TextRedactor;+}): Promise<void> {+ while (!input.signal.aborted && !input.state.terminal) {+ await delay(input.intervalMs, input.signal);+ if (input.signal.aborted || input.state.terminal) break;+ try {+ const status = await fetchJson(apiUrl(input.baseUrl, `/v1/runs/${encodeURIComponent(input.state.runId)}`), {+ method: "GET",+ headers: input.headers,+ signal: input.signal,+ });+ const normalized = extractStatus(status);+ if (normalized && TERMINAL_STATUSES.has(normalized)) {+ markTerminal(input.state, {+ runId: input.state.runId,+ status: normalized,+ payload: asRecord(status),+ output: extractOutput(status),+ });+ }+ } catch (err) {+ if (input.signal.aborted) return;+ await input.ctx.onLog("stderr", `[hermes-gateway] status poll failed: ${redactErrorMessage(err, input.redactText)}\n`);+ }+ }+}++async function consumeEvents(input: {+ ctx: AdapterExecutionContext;+ baseUrl: URL;+ headers: Record<string, string>;+ state: ExecutionState;+ signal: AbortSignal;+ reconnectMs: number;+ redactText?: TextRedactor;+}): Promise<void> {+ while (!input.signal.aborted && !input.state.terminal) {+ try {+ const response = await fetch(apiUrl(input.baseUrl, `/v1/runs/${encodeURIComponent(input.state.runId)}/events`), {+ method: "GET",+ headers: input.headers,+ signal: input.signal,+ });+ if (!response.ok) {+ await input.ctx.onLog("stderr", `[hermes-gateway] event stream HTTP ${response.status}; falling back to polling\n`);+ await delay(input.reconnectMs, input.signal);+ continue;+ }+ if (!response.body) {+ await input.ctx.onLog("stderr", "[hermes-gateway] event stream response had no body; falling back to polling\n");+ await delay(input.reconnectMs, input.signal);+ continue;+ }+ const reader = response.body.getReader();+ const decoder = new TextDecoder();+ let buffer = "";+ while (!input.signal.aborted && !input.state.terminal) {+ const { value, done } = await reader.read();+ if (done) {+ if (buffer.trim().length > 0) {+ const parsed = parseSseFramesForTest(`${buffer}\n\n`);+ buffer = parsed.rest;+ for (const frame of parsed.frames) {+ await handleEvent(input.ctx, input.state, frame, input.redactText);+ if (input.state.terminal) break;+ }+ }+ break;+ }+ buffer += decoder.decode(value, { stream: true });+ const parsed = parseSseFramesForTest(buffer);+ buffer = parsed.rest;+ for (const frame of parsed.frames) {+ await handleEvent(input.ctx, input.state, frame, input.redactText);+ if (input.state.terminal) break;+ }+ }+ } catch (err) {+ if (input.signal.aborted || input.state.terminal) return;+ await input.ctx.onLog("stderr", `[hermes-gateway] event stream disconnected: ${redactErrorMessage(err, input.redactText)}\n`);+ }+ if (!input.state.terminal) await delay(input.reconnectMs, input.signal);+ }+}++function parseUsage(value: unknown): UsageSummary | undefined {+ const record = asRecord(value);+ if (!record) return undefined;+ const source = asRecord(record.usage) ?? record;+ const inputTokens = asNumber(source.input_tokens ?? source.inputTokens ?? source.input, 0);+ const outputTokens = asNumber(source.output_tokens ?? source.outputTokens ?? source.output, 0);+ const cachedInputTokens = asNumber(source.cached_input_tokens ?? source.cachedInputTokens, 0);+ if (inputTokens <= 0 && outputTokens <= 0 && cachedInputTokens <= 0) return undefined;+ return {+ inputTokens,+ outputTokens,+ ...(cachedInputTokens > 0 ? { cachedInputTokens } : {}),+ };+}++function parseCostUsd(value: unknown): number | null {+ const record = asRecord(value);+ const raw = record?.cost_usd ?? record?.costUsd ?? asRecord(record?.usage)?.cost_usd ?? asRecord(record?.usage)?.costUsd;+ const parsed = typeof raw === "number" ? raw : typeof raw === "string" ? Number.parseFloat(raw) : Number.NaN;+ return Number.isFinite(parsed) ? parsed : null;+}++function extractSessionId(value: unknown): string | null {+ const record = asRecord(value);+ return nonEmpty(record?.session_id) ?? nonEmpty(record?.sessionId) ?? nonEmpty(asRecord(record?.data)?.session_id);+}++function extractModel(value: unknown): string | null {+ const record = asRecord(value);+ return nonEmpty(record?.model) ?? nonEmpty(asRecord(record?.usage)?.model);+}++function extractErrorMessage(value: unknown): string | null {+ const record = asRecord(value);+ return nonEmpty(record?.error) ?? nonEmpty(record?.message) ?? nonEmpty(record?.detail) ?? extractOutput(value);+}++function terminalResultCode(status: string): { exitCode: number; signal: string | null; errorCode: string | null } {+ if (status === "completed") return { exitCode: 0, signal: null, errorCode: null };+ if (FAILURE_STATUSES.has(status)) return { exitCode: 1, signal: null, errorCode: "hermes_gateway_run_failed" };+ if (CANCELLED_STATUSES.has(status)) return { exitCode: 1, signal: "SIGTERM", errorCode: "hermes_gateway_cancelled" };+ return { exitCode: 1, signal: null, errorCode: "hermes_gateway_protocol_error" };+}++export function mapFinalResultForTest(input: {+ terminal: TerminalState;+ outputChunks: string[];+ sessionKey: string | null;+ strategy: SessionKeyStrategy;+ redactText?: TextRedactor;+}): AdapterExecutionResult {+ const redactText = input.redactText ?? sanitizeSensitiveText;+ const payload = input.terminal.payload ?? {};+ const output = redactText(+ input.terminal.output ?? extractOutput(payload) ?? input.outputChunks.join("").trim(),+ );+ const sessionId = extractSessionId(payload) ?? input.sessionKey;+ const sessionDisplayId = sessionId ? redactText(sessionId) : null;+ const mapped = terminalResultCode(input.terminal.status);+ const usage = parseUsage(payload);+ const costUsd = parseCostUsd(payload);+ const errorMessage = mapped.errorCode+ ? redactText(extractErrorMessage(payload) ?? `Hermes run ${input.terminal.status}`)+ : null;+ return {+ exitCode: mapped.exitCode,+ signal: mapped.signal,+ timedOut: false,+ provider: "hermes_gateway",+ model: extractModel(payload),+ ...(mapped.errorCode ? { errorCode: mapped.errorCode } : {}),+ ...(errorMessage ? { errorMessage } : {}),+ ...(usage ? { usage } : {}),+ ...(costUsd !== null ? { costUsd } : {}),+ ...(output ? { summary: output.slice(0, 2_000) } : {}),+ sessionId: sessionDisplayId,+ sessionParams: {+ hermesRunId: input.terminal.runId,+ ...(sessionId && sessionDisplayId === sessionId ? { hermesSessionId: sessionId } : {}),+ strategy: input.strategy,+ },+ sessionDisplayId,+ resultJson: {+ run_id: input.terminal.runId,+ status: input.terminal.status,+ session_id: sessionDisplayId,+ last_event: input.terminal.eventName ?? null,+ output: output ?? "",+ usage: usage ?? null,+ cost_usd: costUsd,+ },+ };+}++async function stopRun(input: {+ ctx: AdapterExecutionContext;+ baseUrl: URL;+ headers: Record<string, string>;+ runId: string;+ redactText?: TextRedactor;+}): Promise<Record<string, unknown> | null> {+ try {+ const stopped = await fetchJson(apiUrl(input.baseUrl, `/v1/runs/${encodeURIComponent(input.runId)}/stop`), {+ method: "POST",+ headers: input.headers,+ });+ await input.ctx.onLog("stdout", `[hermes-gateway] stop requested for run ${input.runId}\n`);+ return asRecord(stopped);+ } catch (err) {+ await input.ctx.onLog("stderr", `[hermes-gateway] stop request failed: ${redactErrorMessage(err, input.redactText)}\n`);+ return null;+ }+}++async function fetchFinalStatus(input: {+ baseUrl: URL;+ headers: Record<string, string>;+ runId: string;+ deadlineMs: number;+}): Promise<Record<string, unknown> | null> {+ const deadline = Date.now() + input.deadlineMs;+ while (Date.now() < deadline) {+ try {+ const status = await fetchJson(apiUrl(input.baseUrl, `/v1/runs/${encodeURIComponent(input.runId)}`), {+ method: "GET",+ headers: input.headers,+ });+ const record = asRecord(status);+ const normalized = extractStatus(status);+ if (normalized && TERMINAL_STATUSES.has(normalized)) return record;+ } catch {+ return null;+ }+ await new Promise((resolve) => setTimeout(resolve, 500));+ }+ return null;+}++function redactErrorMessage(err: unknown, redactText: TextRedactor = sanitizeSensitiveText): string {+ if (err instanceof Error) return redactText(err.message);+ return redactText(String(err));+}++function errorResult(err: unknown, redactText: TextRedactor = sanitizeSensitiveText): AdapterExecutionResult {+ const hermesError = err as HermesHttpError;+ const code = hermesError.code ?? "hermes_gateway_protocol_error";+ const classified = hermesError.status ? classifyHttpError(hermesError.status) : null;+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorCode: code,+ errorFamily: classified?.family ?? (code === "hermes_gateway_connect_failed" ? "transient_upstream" : null),+ retryNotBefore: hermesError.retryNotBefore ?? null,+ errorMessage: redactErrorMessage(err, redactText),+ errorMeta: {+ ...(hermesError.status ? { status: hermesError.status } : {}),+ ...(hermesError.body ? { body: redactForLog(hermesError.body, [], 0, redactText) as Record<string, unknown> } : {}),+ },+ };+}++export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExecutionResult> {+ const apiBaseUrlValue = asString(ctx.config.apiBaseUrl ?? ctx.config.url, "").trim();+ if (!apiBaseUrlValue) {+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorCode: "hermes_gateway_api_base_url_missing",+ errorMessage: "Hermes gateway adapter requires apiBaseUrl.",+ };+ }++ const baseUrl = normalizeBaseUrl(apiBaseUrlValue);+ if (!baseUrl) {+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorCode: "hermes_gateway_api_base_url_invalid",+ errorMessage: `Invalid Hermes gateway apiBaseUrl: ${apiBaseUrlValue}`,+ };+ }+ if (isRemotePlainHttp(baseUrl) && !allowsInsecureRemoteHttp(ctx.config)) {+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorCode: "hermes_gateway_plain_http_remote_denied",+ errorMessage: remotePlainHttpDeniedMessage(baseUrl.hostname),+ };+ }++ const apiKey = nonEmpty(ctx.config.apiKey) ?? nonEmpty(ctx.config.token);+ if (!apiKey) {+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorCode: "hermes_gateway_api_key_missing",+ errorMessage: "Hermes gateway adapter requires apiKey.",+ };+ }++ const timeoutSec = parseNonNegativeNumber(ctx.config.timeoutSec, DEFAULT_TIMEOUT_SEC);+ const timeoutMs = timeoutSec > 0 ? Math.ceil(timeoutSec * 1000) : 0;+ const reconnectMs = Math.floor(clamp(parseNonNegativeNumber(ctx.config.eventReconnectMs, DEFAULT_EVENT_RECONNECT_MS), 250, 30_000));+ const pollIntervalMs = Math.floor(clamp(parseNonNegativeNumber(ctx.config.pollIntervalMs, DEFAULT_POLL_INTERVAL_MS), 250, 10_000));+ const strategy = normalizeSessionKeyStrategy(ctx.config.sessionKeyStrategy);+ const sessionKey = resolveSessionKey({+ strategy,+ companyId: ctx.agent.companyId,+ agentId: ctx.agent.id,+ runId: ctx.runId,+ issueId: issueIdFromContext(ctx),+ });+ const extraHeaders = parseHeaders(ctx.config.headers);+ const runHeaders = buildHeaders({+ apiKey,+ sessionKey,+ runId: ctx.runId,+ extraHeaders,+ accept: "application/json",+ contentType: "application/json",+ });+ const eventHeaders = buildHeaders({+ apiKey,+ sessionKey,+ runId: ctx.runId,+ extraHeaders,+ accept: "text/event-stream",+ });+ const redactText = createTextRedactor([+ apiKey,+ sessionKey,+ runHeaders.Authorization,+ runHeaders["X-Hermes-Session-Key"],+ ]);+ const body = buildRunBody(ctx, sessionKey);++ await ctx.onMeta?.({+ adapterType: ADAPTER_TYPE,+ command: "POST /v1/runs",+ commandArgs: [baseUrl.origin, "/v1/runs"],+ context: {+ runId: ctx.runId,+ timeoutSec,+ eventReconnectMs: reconnectMs,+ sessionKeyStrategy: strategy,+ hasSessionKey: Boolean(sessionKey),+ },+ });+ await ctx.onLog("stdout", `[hermes-gateway] creating run at ${baseUrl.origin}/v1/runs (timeout=${timeoutSec}s, session=${strategy})\n`);+ await ctx.onLog("stdout", `[hermes-gateway] request headers (redacted): ${stringifyForLog(redactForLog(runHeaders, [], 0, redactText), 3_000)}\n`);++ let runId: string | null = null;+ try {+ const created = await fetchJson(apiUrl(baseUrl, "/v1/runs"), {+ method: "POST",+ headers: runHeaders,+ body: JSON.stringify(body),+ });+ runId = extractRunId(created);+ if (!runId) {+ return {+ exitCode: 1,+ signal: null,+ timedOut: false,+ errorCode: "hermes_gateway_protocol_error",+ errorMessage: "Hermes /v1/runs response did not include run_id.",+ errorMeta: { response: redactForLog(created, [], 0, redactText) as Record<string, unknown> },+ };+ }+ } catch (err) {+ return errorResult(err, redactText);+ }++ await ctx.onLog("stdout", `[hermes-gateway] run created: ${runId}\n`);++ const state = createExecutionState(runId);+ const controller = new AbortController();+ void consumeEvents({+ ctx,+ baseUrl,+ headers: eventHeaders,+ state,+ signal: controller.signal,+ reconnectMs,+ redactText,+ }).catch(() => undefined);+ void pollStatus({+ ctx,+ baseUrl,+ headers: eventHeaders,+ state,+ signal: controller.signal,+ intervalMs: pollIntervalMs,+ redactText,+ }).catch(() => undefined);++ let timeoutTimer: ReturnType<typeof setTimeout> | null = null;+ const timeoutPromise = new Promise<"timeout">((resolve) => {+ if (timeoutMs <= 0) return;+ timeoutTimer = setTimeout(() => resolve("timeout"), timeoutMs);+ });++ const outcome = await Promise.race([state.terminalPromise, timeoutPromise]);+ if (timeoutTimer) clearTimeout(timeoutTimer);+ controller.abort();++ if (outcome === "timeout") {+ await stopRun({ ctx, baseUrl, headers: eventHeaders, runId, redactText });+ const finalStatus = await fetchFinalStatus({ baseUrl, headers: eventHeaders, runId, deadlineMs: STOP_GRACE_MS });+ return {+ exitCode: 1,+ signal: null,+ timedOut: true,+ errorCode: "hermes_gateway_timeout",+ errorMessage: `Hermes gateway run timed out after ${timeoutSec}s.`,+ provider: "hermes_gateway",+ resultJson: {+ run_id: runId,+ status: extractStatus(finalStatus) ?? "timeout",+ last_event: state.lastEventName,+ final_status: redactForLog(finalStatus, [], 0, redactText),+ },+ sessionParams: {+ hermesRunId: runId,+ strategy,+ },+ sessionDisplayId: sessionKey ? redactText(sessionKey) : null,+ };+ }++ return mapFinalResultForTest({+ terminal: outcome,+ outputChunks: state.outputChunks,+ sessionKey,+ strategy,+ redactText,+ });+}diff --git a/packages/adapters/hermes/src/gateway/server/index.ts b/packages/adapters/hermes/src/gateway/server/index.tsnew file mode 100644index 0000000000..b29873d6ec--- /dev/null+++ b/packages/adapters/hermes/src/gateway/server/index.ts@@ -0,0 +1,45 @@+import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";++export { execute, resolveSessionKey, parseSseFramesForTest, mapFinalResultForTest } from "./execute.js";+export { testEnvironment } from "./test.js";+export { getConfigSchema } from "./config-schema.js";++function readString(value: unknown): string | null {+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;+}++export const sessionCodec: AdapterSessionCodec = {+ deserialize(raw) {+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;+ const record = raw as Record<string, unknown>;+ const hermesSessionId = readString(record.hermesSessionId) ?? readString(record.sessionId);+ const sessionKey = readString(record.sessionKey);+ const hermesRunId = readString(record.hermesRunId);+ const strategy = readString(record.strategy);+ if (!hermesSessionId && !sessionKey && !hermesRunId) return null;+ return {+ ...(hermesRunId ? { hermesRunId } : {}),+ ...(hermesSessionId ? { hermesSessionId } : {}),+ ...(sessionKey ? { sessionKey } : {}),+ ...(strategy ? { strategy } : {}),+ };+ },+ serialize(params) {+ if (!params) return null;+ const hermesSessionId = readString(params.hermesSessionId) ?? readString(params.sessionId);+ const sessionKey = readString(params.sessionKey);+ const hermesRunId = readString(params.hermesRunId);+ const strategy = readString(params.strategy);+ if (!hermesSessionId && !sessionKey && !hermesRunId) return null;+ return {+ ...(hermesRunId ? { hermesRunId } : {}),+ ...(hermesSessionId ? { hermesSessionId } : {}),+ ...(sessionKey ? { sessionKey } : {}),+ ...(strategy ? { strategy } : {}),+ };+ },+ getDisplayId(params) {+ if (!params) return null;+ return readString(params.hermesSessionId) ?? readString(params.sessionKey) ?? readString(params.hermesRunId);+ },+};diff --git a/packages/adapters/hermes/src/gateway/server/test.ts b/packages/adapters/hermes/src/gateway/server/test.tsnew file mode 100644index 0000000000..da601a3e81--- /dev/null+++ b/packages/adapters/hermes/src/gateway/server/test.ts@@ -0,0 +1,127 @@+import type {+ AdapterEnvironmentCheck,+ AdapterEnvironmentTestContext,+ AdapterEnvironmentTestResult,+} from "@paperclipai/adapter-utils";+import { asString } from "@paperclipai/adapter-utils/server-utils";+import {+ allowsInsecureRemoteHttp,+ isLoopbackHostname,+ isRemotePlainHttp,+ remotePlainHttpDeniedMessage,+} from "./transport-security.js";++function summarizeStatus(checks: AdapterEnvironmentCheck[]): AdapterEnvironmentTestResult["status"] {+ if (checks.some((check) => check.level === "error")) return "fail";+ if (checks.some((check) => check.level === "warn")) return "warn";+ return "pass";+}++function normalizeBaseUrl(value: string): URL | null {+ try {+ const url = new URL(value);+ if (url.protocol !== "http:" && url.protocol !== "https:") return null;+ return url;+ } catch {+ return null;+ }+}++export async function testEnvironment(+ ctx: AdapterEnvironmentTestContext,+): Promise<AdapterEnvironmentTestResult> {+ const checks: AdapterEnvironmentCheck[] = [];+ const apiBaseUrl = asString(ctx.config.apiBaseUrl ?? ctx.config.url, "").trim();+ const apiKey = asString(ctx.config.apiKey ?? ctx.config.token, "").trim();++ if (!apiBaseUrl) {+ checks.push({+ code: "hermes_gateway_api_base_url_missing",+ level: "error",+ message: "Hermes Gateway requires apiBaseUrl.",+ hint: "Enable Hermes API server and set apiBaseUrl, for example http://127.0.0.1:8642.",+ });+ }++ const parsed = apiBaseUrl ? normalizeBaseUrl(apiBaseUrl) : null;+ if (apiBaseUrl && !parsed) {+ checks.push({+ code: "hermes_gateway_api_base_url_invalid",+ level: "error",+ message: "apiBaseUrl must be an http:// or https:// URL.",+ });+ }++ if (!apiKey) {+ checks.push({+ code: "hermes_gateway_api_key_missing",+ level: "error",+ message: "Hermes Gateway requires apiKey.",+ hint: "Set Hermes API_SERVER_KEY and copy the same value into adapterConfig.apiKey.",+ });+ }++ if (parsed && isRemotePlainHttp(parsed) && !allowsInsecureRemoteHttp(ctx.config)) {+ checks.push({+ code: "hermes_gateway_plain_http_remote_denied",+ level: "error",+ message: remotePlainHttpDeniedMessage(parsed.hostname),+ hint: "Use https:// for remote Hermes gateways. Loopback http://localhost and http://127.0.0.1 remain allowed.",+ });+ } else if (parsed && isRemotePlainHttp(parsed)) {+ checks.push({+ code: "hermes_gateway_plain_http_remote_unsafe_allowed",+ level: "warn",+ message: "Unsafe dev escape hatch enabled for non-loopback HTTP Hermes traffic.",+ hint: "Remove the escape hatch and use HTTPS before using this gateway for real credentials.",+ });+ } else if (parsed?.protocol === "http:" && isLoopbackHostname(parsed.hostname)) {+ checks.push({+ code: "hermes_gateway_loopback_http_allowed",+ level: "info",+ message: "Loopback HTTP Hermes gateway URL is allowed.",+ });+ }++ if (checks.some((check) => check.level === "error") || !parsed || !apiKey) {+ return {+ adapterType: ctx.adapterType,+ status: summarizeStatus(checks),+ checks,+ testedAt: new Date().toISOString(),+ };+ }++ try {+ const healthUrl = new URL("/health", parsed);+ const response = await fetch(healthUrl, {+ method: "GET",+ headers: {+ Authorization: `Bearer ${apiKey}`,+ Accept: "application/json",+ },+ signal: AbortSignal.timeout(2_000),+ });+ checks.push({+ code: response.ok ? "hermes_gateway_health_ok" : "hermes_gateway_health_failed",+ level: response.ok ? "info" : "warn",+ message: response.ok+ ? "Hermes Gateway health endpoint is reachable."+ : `Hermes Gateway health endpoint returned HTTP ${response.status}.`,+ });+ } catch (err) {+ checks.push({+ code: "hermes_gateway_health_unreachable",+ level: "warn",+ message: "Could not reach Hermes Gateway health endpoint.",+ detail: err instanceof Error ? err.message : String(err),+ });+ }++ return {+ adapterType: ctx.adapterType,+ status: summarizeStatus(checks),+ checks,+ testedAt: new Date().toISOString(),+ };+}diff --git a/packages/adapters/hermes/src/gateway/server/transport-security.ts b/packages/adapters/hermes/src/gateway/server/transport-security.tsnew file mode 100644index 0000000000..00d7deceff--- /dev/null+++ b/packages/adapters/hermes/src/gateway/server/transport-security.ts@@ -0,0 +1,36 @@+export const INSECURE_REMOTE_HTTP_ESCAPE_HATCH = "dangerouslyAllowInsecureRemoteHttp";++export function parseBooleanLike(value: unknown): boolean | null {+ if (typeof value === "boolean") return value;+ if (typeof value !== "string") return null;+ const normalized = value.trim().toLowerCase();+ if (["1", "true", "yes", "on"].includes(normalized)) return true;+ if (["0", "false", "no", "off"].includes(normalized)) return false;+ return null;+}++export function isLoopbackHostname(hostname: string): boolean {+ const value = hostname.toLowerCase().replace(/^\[|\]$/g, "");+ return (+ value === "localhost" ||+ value === "::1" ||+ value === "0:0:0:0:0:0:0:1" ||+ value === "127.0.0.1" ||+ /^127(?:\.\d{1,3}){3}$/.test(value)+ );+}++export function isRemotePlainHttp(url: URL): boolean {+ return url.protocol === "http:" && !isLoopbackHostname(url.hostname);+}++export function allowsInsecureRemoteHttp(config: Record<string, unknown>): boolean {+ return parseBooleanLike(config[INSECURE_REMOTE_HTTP_ESCAPE_HATCH]) === true;+}++export function remotePlainHttpDeniedMessage(hostname: string): string {+ return (+ `Hermes gateway apiBaseUrl uses remote plain HTTP for "${hostname}". ` ++ `Use HTTPS or set ${INSECURE_REMOTE_HTTP_ESCAPE_HATCH}=true only for unsafe local development.`+ );+}diff --git a/packages/adapters/hermes/src/gateway/shared/constants.ts b/packages/adapters/hermes/src/gateway/shared/constants.tsnew file mode 100644index 0000000000..de974c47a7--- /dev/null+++ b/packages/adapters/hermes/src/gateway/shared/constants.ts@@ -0,0 +1,7 @@+export const ADAPTER_TYPE = "hermes_gateway";+export const ADAPTER_LABEL = "Hermes Gateway";++export const DEFAULT_TIMEOUT_SEC = 120;+export const DEFAULT_EVENT_RECONNECT_MS = 2_000;+export const DEFAULT_POLL_INTERVAL_MS = 1_000;+export const STOP_GRACE_MS = 10_000;diff --git a/packages/adapters/hermes/src/gateway/ui/index.ts b/packages/adapters/hermes/src/gateway/ui/index.tsnew file mode 100644index 0000000000..eae592b1e0--- /dev/null+++ b/packages/adapters/hermes/src/gateway/ui/index.ts@@ -0,0 +1 @@+export { parseHermesGatewayStdoutLine as parseStdoutLine } from "./parse-stdout.js";diff --git a/packages/adapters/hermes/src/gateway/ui/parse-stdout.ts b/packages/adapters/hermes/src/gateway/ui/parse-stdout.tsnew file mode 100644index 0000000000..df9db752dd--- /dev/null+++ b/packages/adapters/hermes/src/gateway/ui/parse-stdout.ts@@ -0,0 +1,47 @@+import type { TranscriptEntry } from "@paperclipai/adapter-utils";++function safeJsonParse(text: string): unknown {+ try {+ return JSON.parse(text);+ } catch {+ return null;+ }+}++function asRecord(value: unknown): Record<string, unknown> | null {+ if (typeof value !== "object" || value === null || Array.isArray(value)) return null;+ return value as Record<string, unknown>;+}++function asString(value: unknown): string {+ return typeof value === "string" ? value : "";+}++export function parseHermesGatewayStdoutLine(line: string, ts: string): TranscriptEntry[] {+ const trimmed = line.trim();+ if (!trimmed) return [];++ const eventMatch = trimmed.match(/^\[hermes-gateway:event\]\s+run=([^\s]+)\s+event=([^\s]+)\s+data=(.*)$/s);+ if (eventMatch) {+ const eventName = eventMatch[2];+ const data = asRecord(safeJsonParse(eventMatch[3]));+ if (eventName === "message.delta") {+ const delta = asString(data?.delta) || asString(data?.text_delta);+ return delta ? [{ kind: "assistant", ts, text: delta, delta: true }] : [];+ }+ if (eventName === "run.failed" || eventName === "run.error") {+ const message = asString(data?.error) || asString(data?.message) || "Hermes run failed";+ return [{ kind: "stderr", ts, text: message }];+ }+ if (eventName === "reasoning.available") {+ return [{ kind: "thinking", ts, text: "Hermes reasoning available" }];+ }+ return [{ kind: "system", ts, text: `Hermes event: ${eventName}` }];+ }++ if (trimmed.startsWith("[hermes-gateway]")) {+ return [{ kind: "system", ts, text: trimmed.replace(/^\[hermes-gateway\]\s*/, "") }];+ }++ return [{ kind: "stdout", ts, text: line }];+}diff --git a/packages/adapters/hermes/src/index.test.ts b/packages/adapters/hermes/src/index.test.tsnew file mode 100644index 0000000000..03e8809262--- /dev/null+++ b/packages/adapters/hermes/src/index.test.ts@@ -0,0 +1,63 @@+import { expect, test } from "vitest";++import {+ createHermesGatewayServerAdapter,+ createHermesLocalServerAdapter,+ createServerAdapter,+ hermesGatewayType,+} from "./index.js";+import { createServerAdapter as createGatewayServerAdapterFromSubpath } from "./gateway/index.js";++test("root package export exposes Paperclip external adapter entrypoint", () => {+ const adapter = createServerAdapter();++ expect(adapter.type).toBe("hermes_local");+ expect(typeof adapter.execute).toBe("function");+ expect(typeof adapter.testEnvironment).toBe("function");+ expect(typeof adapter.sessionCodec?.deserialize).toBe("function");+ expect(adapter.sessionManagement?.nativeContextManagement).toBe("confirmed");+ expect(adapter.supportsLocalAgentJwt).toBe(true);+ expect(adapter.supportsInstructionsBundle).toBe(true);+ expect(adapter.instructionsPathKey).toBe("instructionsFilePath");+ expect(adapter.getRuntimeCommandSpec?.({ command: "hermes-dev" })).toMatchObject({+ command: "hermes-dev",+ detectCommand: "hermes-dev",+ installCommand: null,+ });+ expect(typeof adapter.detectModel).toBe("function");+ expect(typeof adapter.getConfigSchema).toBe("function");+});++test("root package export keeps explicit local and gateway adapter factories", () => {+ const localAdapter = createHermesLocalServerAdapter();+ const gatewayAdapter = createHermesGatewayServerAdapter();++ expect(localAdapter.type).toBe("hermes_local");+ expect(gatewayAdapter.type).toBe("hermes_gateway");+ expect(hermesGatewayType).toBe("hermes_gateway");+ expect(gatewayAdapter.supportsLocalAgentJwt).toBe(false);+ expect(gatewayAdapter.supportsInstructionsBundle).toBe(false);+});++test("gateway subpath export exposes the Hermes Gateway adapter entrypoint", () => {+ const adapter = createGatewayServerAdapterFromSubpath();++ expect(adapter.type).toBe("hermes_gateway");+ expect(typeof adapter.execute).toBe("function");+ expect(typeof adapter.testEnvironment).toBe("function");+ expect(typeof adapter.sessionCodec?.deserialize).toBe("function");+ expect(adapter.sessionManagement?.nativeContextManagement).toBe("confirmed");+ expect(typeof adapter.getConfigSchema).toBe("function");+});++test("Hermes adapter exposes bundled Paperclip task bridge skill", async () => {+ const adapter = createServerAdapter();+ const snapshot = await adapter.listSkills?.({+ adapterType: "hermes_local",+ agentId: "11111111-1111-4111-8111-111111111111",+ companyId: "22222222-2222-4222-8222-222222222222",+ config: {},+ });++ expect(snapshot?.entries.some((entry) => entry.runtimeName === "paperclip-task-bridge")).toBe(true);+});diff --git a/packages/adapters/hermes/src/index.ts b/packages/adapters/hermes/src/index.tsnew file mode 100644index 0000000000..3494bf5970--- /dev/null+++ b/packages/adapters/hermes/src/index.ts@@ -0,0 +1,176 @@+/**+ * Hermes Agent adapter for Paperclip.+ *+ * Runs Hermes Agent (https://github.com/NousResearch/hermes-agent)+ * as a managed employee in a Paperclip company. Hermes Agent is a+ * full-featured AI agent with 30+ native tools, persistent memory,+ * skills, session persistence, and MCP support.+ *+ * @packageDocumentation+ */++import type {+ AdapterRuntimeCommandSpec,+ AdapterSessionManagement,+ ServerAdapterModule,+} from "@paperclipai/adapter-utils";++import { ADAPTER_TYPE, ADAPTER_LABEL } from "./shared/constants.js";+import {+ execute,+ testEnvironment,+ sessionCodec,+ listSkills,+ syncSkills,+ detectModel,+ getConfigSchema,+} from "./server/index.js";+import { resolveHermesCommand } from "./server/execute.js";++export const type = ADAPTER_TYPE;+export const label = ADAPTER_LABEL;+export {+ createServerAdapter as createHermesGatewayServerAdapter,+ agentConfigurationDoc as hermesGatewayAgentConfigurationDoc,+ label as hermesGatewayLabel,+ models as hermesGatewayModels,+ type as hermesGatewayType,+} from "./gateway/index.js";++/**+ * Models available through Hermes Agent.+ *+ * Hermes supports any model via any provider. The Paperclip UI should+ * prefer detectModel() plus manual entry over curated placeholder models,+ * since Hermes availability depends on the user's local configuration.+ */+export const models: { id: string; label: string }[] = [];++const sessionManagement: AdapterSessionManagement = {+ supportsSessionResume: true,+ nativeContextManagement: "confirmed",+ defaultSessionCompaction: {+ enabled: true,+ maxSessionRuns: 0,+ maxRawInputTokens: 0,+ maxSessionAgeHours: 0,+ },+};++function getRuntimeCommandSpec(config: Record<string, unknown>): AdapterRuntimeCommandSpec {+ const command = resolveHermesCommand(config);+ return {+ command,+ detectCommand: command,+ installCommand: null,+ };+}++/**+ * Documentation shown in the Paperclip UI when configuring a Hermes agent.+ */+export const agentConfigurationDoc = `# Hermes Agent Configuration++Hermes Agent is a full-featured AI agent by Nous Research with 30+ native+tools, persistent memory, session persistence, skills, and MCP support.++## Prerequisites++- Python 3.10+ installed+- Hermes Agent installed: \`pip install hermes-agent\`+- At least one LLM API key configured in ~/.hermes/.env++## Core Configuration++| Field | Type | Default | Description |+|-------|------|---------|-------------|+| model | string | (Hermes configured default) | Optional explicit model in provider/model format. Leave blank to use Hermes's configured default model. |+| provider | string | (auto) | API provider: auto, openrouter, nous, openai-codex, zai, kimi-coding, minimax, minimax-cn. Usually not needed — Hermes auto-detects from model name. |+| timeoutSec | number | 300 | Execution timeout in seconds |+| graceSec | number | 10 | Grace period after SIGTERM before SIGKILL |++## Tool Configuration++| Field | Type | Default | Description |+|-------|------|---------|-------------|+| toolsets | string | (all) | Comma-separated toolsets to enable (e.g. "terminal,file,web") |++## Session & Workspace++| Field | Type | Default | Description |+|-------|------|---------|-------------|+| persistSession | boolean | true | Resume sessions across heartbeats |+| worktreeMode | boolean | false | Use git worktree for isolated changes |+| checkpoints | boolean | false | Enable filesystem checkpoints |++## Advanced++| Field | Type | Default | Description |+|-------|------|---------|-------------|+| hermesCommand | string | hermes | Path to hermes CLI binary |+| verbose | boolean | false | Enable verbose output |+| extraArgs | string[] | [] | Additional CLI arguments |+| env | object | {} | Extra environment variables |+| promptTemplate | string | (default) | Custom prompt template with {{variable}} placeholders |++## Hermes-Originated Paperclip Tasks++This adapter package also ships a Hermes-facing Paperclip task bridge skill:+\`paperclip-task-bridge\`. Use it when a user starts in Hermes and asks Hermes+to create, comment on, update, or list Paperclip tasks.++Configure credentials through Hermes env/profile secrets, never in prompt text:++- \`PAPERCLIP_API_URL\` - Paperclip base URL, with or without \`/api\`+- \`PAPERCLIP_BRIDGE_API_KEY\` - Paperclip agent API key created with \`scope.kind = "task_bridge"\`+- optional fallback \`PAPERCLIP_API_KEY\` - must still be a task_bridge key, never a normal claimed agent key+- optional \`PAPERCLIP_COMPANY_ID\`, \`PAPERCLIP_AGENT_ID\`, and \`PAPERCLIP_RUN_ID\`++The bridge is separate from adapter execution:++- \`hermes_local\` means Paperclip shells out to local \`hermes chat\`.+- \`hermes_gateway\` means Paperclip wakes remote Hermes through Hermes's API server.+- \`paperclip-task-bridge\` means Hermes calls Paperclip's REST API to manage tasks.++Create task bridge keys with a parent issue or project boundary. Do not expose+normal claimed Paperclip agent API keys to internet-facing Hermes chat/webhook+task-bridge surfaces.++## Available Template Variables++- \`{{agentId}}\` — Paperclip agent ID+- \`{{agentName}}\` — Agent display name+- \`{{companyId}}\` — Paperclip company ID+- \`{{companyName}}\` — Company display name+- \`{{runId}}\` — Current heartbeat run ID+- \`{{taskId}}\` — Current task/issue ID (if assigned)+- \`{{taskTitle}}\` — Task title (if assigned)+- \`{{taskBody}}\` — Task description (if assigned)+- \`{{projectName}}\` — Project name (if scoped to a project)+`;++/**+ * External adapter plugin entrypoint expected by Paperclip's adapter manager.+ */+export function createServerAdapter(): ServerAdapterModule {+ return {+ type,+ execute,+ testEnvironment,+ sessionCodec,+ sessionManagement,+ listSkills,+ syncSkills,+ models,+ supportsLocalAgentJwt: true,+ supportsInstructionsBundle: true,+ instructionsPathKey: "instructionsFilePath",+ requiresMaterializedRuntimeSkills: false,+ getRuntimeCommandSpec,+ agentConfigurationDoc,+ detectModel,+ getConfigSchema,+ };+}++export { createServerAdapter as createHermesLocalServerAdapter };diff --git a/packages/adapters/hermes/src/server/command-resolution.test.ts b/packages/adapters/hermes/src/server/command-resolution.test.tsnew file mode 100644index 0000000000..0462ad5a0c--- /dev/null+++ b/packages/adapters/hermes/src/server/command-resolution.test.ts@@ -0,0 +1,48 @@+import os from "node:os";+import path from "node:path";+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";+import { expect, test } from "vitest";++import { HERMES_CLI } from "../shared/constants.js";+import { resolveHermesCommand } from "./execute.js";+import { testEnvironment } from "./test.js";++test("resolveHermesCommand prefers hermesCommand over command", () => {+ expect(resolveHermesCommand({ hermesCommand: "hermes_maximus", command: "hermes_backup" }))+ .toBe("hermes_maximus");+});++test("resolveHermesCommand falls back to command before default hermes binary", () => {+ expect(resolveHermesCommand({ command: "hermes_maximus" })).toBe("hermes_maximus");+ expect(resolveHermesCommand({})).toBe(HERMES_CLI);+});++test("testEnvironment accepts config.command when hermesCommand is absent", async () => {+ const tempDir = await mkdtemp(path.join(os.tmpdir(), "hermes-command-resolution-"));+ const cliPath = path.join(tempDir, "fake-hermes");++ try {+ await writeFile(+ cliPath,+ "#!/bin/sh\necho fake-hermes 1.2.3\n",+ "utf8",+ );+ await chmod(cliPath, 0o755);++ const result = await testEnvironment({+ companyId: "company-test",+ adapterType: "hermes_local",+ config: {+ command: cliPath,+ },+ });++ expect(result.status).not.toBe("fail");+ expect(result.checks.some((check) => check.code === "hermes_cli_not_found")).toBe(false);+ expect(result.checks.some(+ (check) => check.code === "hermes_version" && check.message.includes("fake-hermes 1.2.3"),+ )).toBe(true);+ } finally {+ await rm(tempDir, { recursive: true, force: true });+ }+});diff --git a/packages/adapters/hermes/src/server/config-schema.ts b/packages/adapters/hermes/src/server/config-schema.tsnew file mode 100644index 0000000000..25d3a5bd69--- /dev/null+++ b/packages/adapters/hermes/src/server/config-schema.ts@@ -0,0 +1,108 @@+import type { AdapterConfigSchema } from "@paperclipai/adapter-utils";++import {+ DEFAULT_GRACE_SEC,+ DEFAULT_TIMEOUT_SEC,+ VALID_PROVIDERS,+} from "../shared/constants.js";++function providerLabel(provider: string): string {+ if (provider === "auto") return "Auto";+ if (provider === "openai-codex") return "OpenAI Codex";+ if (provider === "kimi-coding") return "Kimi Coding";+ if (provider === "minimax-cn") return "MiniMax China";+ return provider+ .split("-")+ .map((part) => part.charAt(0).toUpperCase() + part.slice(1))+ .join(" ");+}++export function getConfigSchema(): AdapterConfigSchema {+ return {+ fields: [+ {+ key: "provider",+ label: "Provider",+ type: "select",+ default: "auto",+ options: VALID_PROVIDERS.map((provider) => ({+ value: provider,+ label: providerLabel(provider),+ })),+ hint: "Usually auto. Set this only when Hermes cannot infer the provider from the model or ~/.hermes/config.yaml.",+ },+ {+ key: "timeoutSec",+ label: "Timeout seconds",+ type: "number",+ default: DEFAULT_TIMEOUT_SEC,+ },+ {+ key: "graceSec",+ label: "Grace seconds",+ type: "number",+ default: DEFAULT_GRACE_SEC,+ hint: "Seconds to wait after SIGTERM before killing the Hermes process.",+ },+ {+ key: "maxTurnsPerRun",+ label: "Max turns per run",+ type: "number",+ hint: "Optional Hermes --max-turns limit for tool-calling iterations.",+ },+ {+ key: "toolsets",+ label: "Toolsets",+ type: "text",+ hint: "Optional comma-separated Hermes toolsets, such as terminal,file,web.",+ },+ {+ key: "persistSession",+ label: "Persist session",+ type: "toggle",+ default: true,+ hint: "Resume Hermes sessions across Paperclip heartbeats.",+ },+ {+ key: "worktreeMode",+ label: "Hermes worktree mode",+ type: "toggle",+ default: false,+ hint: "Pass Hermes --worktree.",+ },+ {+ key: "checkpoints",+ label: "Checkpoints",+ type: "toggle",+ default: false,+ hint: "Pass Hermes --checkpoints.",+ },+ {+ key: "quiet",+ label: "Quiet output",+ type: "toggle",+ default: true,+ hint: "Pass Hermes --quiet for cleaner Paperclip run transcripts.",+ },+ {+ key: "verbose",+ label: "Verbose output",+ type: "toggle",+ default: false,+ hint: "Pass Hermes --verbose.",+ },+ {+ key: "paperclipApiUrl",+ label: "Paperclip API URL",+ type: "text",+ hint: "Optional API base override. Defaults to PAPERCLIP_API_URL.",+ },+ {+ key: "promptTemplate",+ label: "Prompt template",+ type: "textarea",+ hint: "Optional custom prompt template with {{variable}} placeholders.",+ },+ ],+ };+}diff --git a/packages/adapters/hermes/src/server/detect-model.test.ts b/packages/adapters/hermes/src/server/detect-model.test.tsnew file mode 100644index 0000000000..05ee2d8fc3--- /dev/null+++ b/packages/adapters/hermes/src/server/detect-model.test.ts@@ -0,0 +1,186 @@+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, expect, test } from "vitest";++import { parseModelFromConfig, resolveProvider } from "./detect-model.js";+import { testEnvironment } from "./test.js";++const providerEnvKeys = [+ "ANTHROPIC_API_KEY",+ "OPENROUTER_API_KEY",+ "OPENAI_API_KEY",+ "ZAI_API_KEY",+ "KIMI_API_KEY",+ "MINIMAX_API_KEY",+];++const previousEnv = {+ HOME: process.env.HOME,+ USERPROFILE: process.env.USERPROFILE,+ HOMEDRIVE: process.env.HOMEDRIVE,+ HOMEPATH: process.env.HOMEPATH,+ ...Object.fromEntries(providerEnvKeys.map((key) => [key, process.env[key]])),+};++afterEach(async () => {+ for (const [key, value] of Object.entries(previousEnv)) {+ if (value === undefined) {+ delete process.env[key];+ } else {+ process.env[key] = value;+ }+ }+});++test("parseModelFromConfig tracks api_key presence without exposing the raw secret", () => {+ const parsed = parseModelFromConfig([+ "model:",+ " default: oca/gpt-5.4",+ " provider: custom",+ " base_url: https://example.invalid/litellm",+ " api_key: super-secret-value",+ "",+ ].join("\n"));++ expect(parsed).toBeTruthy();+ expect(parsed?.hasApiKey).toBe(true);+ expect(Object.hasOwn(parsed ?? {}, "apiKey")).toBe(false);+});++test("resolveProvider does not fall through to model inference when Hermes config provider is unsupported but matches the requested model", () => {+ expect(resolveProvider({+ explicitProvider: undefined,+ detectedProvider: "custom",+ detectedModel: "oca/gpt-5.4",+ detectedBaseUrl: "https://example.invalid/litellm",+ detectedHasApiKey: true,+ model: "oca/gpt-5.4",+ })).toEqual({+ provider: "auto",+ resolvedFrom: "hermesConfigUnsupported:custom",+ });+});++test("resolveProvider also defers to Hermes runtime when the matching config omits provider but includes runtime signals", () => {+ expect(resolveProvider({+ explicitProvider: undefined,+ detectedProvider: "",+ detectedModel: "oca/gpt-5.4",+ detectedBaseUrl: "https://example.invalid/litellm",+ detectedHasApiKey: true,+ model: "oca/gpt-5.4",+ })).toEqual({+ provider: "auto",+ resolvedFrom: "hermesConfigRuntime",+ });+});++test("resolveProvider still infers from the requested model when Hermes config is for a different model", () => {+ expect(resolveProvider({+ explicitProvider: undefined,+ detectedProvider: "custom",+ detectedModel: "oca/gpt-5.4",+ detectedBaseUrl: "https://example.invalid/litellm",+ detectedHasApiKey: true,+ model: "claude-sonnet-4",+ })).toEqual({+ provider: "anthropic",+ resolvedFrom: "modelInference",+ });+});++async function withHermesHomeConfig(+ configLines: string[],+ fn: () => Promise<void>,+) {+ const tempHome = await mkdtemp(join(tmpdir(), "hermes-paperclip-adapter-"));+ const hermesDir = join(tempHome, ".hermes");+ const configPath = join(hermesDir, "config.yaml");++ await mkdir(hermesDir, { recursive: true });+ await writeFile(configPath, `${configLines.join("\n")}\n`, "utf8");+ process.env.HOME = tempHome;+ process.env.USERPROFILE = tempHome;+ delete process.env.HOMEDRIVE;+ delete process.env.HOMEPATH;+ for (const key of providerEnvKeys) {+ delete process.env[key];+ }++ try {+ await fn();+ } finally {+ await rm(tempHome, { recursive: true, force: true });+ }+}++test("testEnvironment does not warn about missing API keys when Hermes config provides a supported provider api_key", async () => {+ await withHermesHomeConfig([+ "model:",+ " default: openrouter/gpt-4.1-mini",+ " provider: openrouter",+ " api_key: test-secret",+ ], async () => {+ const result = await testEnvironment({+ companyId: "company-test",+ adapterType: "hermes_local",+ config: {+ hermesCommand: "python3",+ model: "openrouter/gpt-4.1-mini",+ },+ });++ const codes = result.checks.map((check) => check.code);++ expect(codes.includes("hermes_no_api_keys")).toBe(false);+ expect(result.status).toBe("pass");+ });+});++test("testEnvironment describes provider-omitted runtime config without inventing provider auto", async () => {+ await withHermesHomeConfig([+ "model:",+ " default: oca/gpt-5.4",+ " base_url: https://example.invalid/litellm",+ " api_key: test-secret",+ ], async () => {+ const result = await testEnvironment({+ companyId: "company-test",+ adapterType: "hermes_local",+ config: {+ hermesCommand: "python3",+ model: "oca/gpt-5.4",+ },+ });++ const apiKeyCheck = result.checks.find((check) => check.code === "hermes_api_key_in_config");+ expect(apiKeyCheck).toBeTruthy();+ expect(apiKeyCheck?.message).toMatch(/without an explicit provider/i);+ expect(apiKeyCheck?.message).not.toMatch(/provider "auto"/i);+ });+});++test("testEnvironment does not warn about missing API keys when Hermes config provides a custom provider base_url and api_key", async () => {+ await withHermesHomeConfig([+ "model:",+ " default: oca/gpt-5.4",+ " provider: custom",+ " base_url: https://example.invalid/litellm",+ " api_key: test-secret",+ ], async () => {+ const result = await testEnvironment({+ companyId: "company-test",+ adapterType: "hermes_local",+ config: {+ hermesCommand: "python3",+ model: "oca/gpt-5.4",+ },+ });++ const codes = result.checks.map((check) => check.code);++ expect(codes.includes("hermes_no_api_keys")).toBe(false);+ expect(result.status).toBe("pass");+ });+});diff --git a/packages/adapters/hermes/src/server/detect-model.ts b/packages/adapters/hermes/src/server/detect-model.tsnew file mode 100644index 0000000000..fc92ca4601--- /dev/null+++ b/packages/adapters/hermes/src/server/detect-model.ts@@ -0,0 +1,217 @@+/**+ * Detect the current model and provider from the user's Hermes config.+ *+ * Reads ~/.hermes/config.yaml and extracts the default model,+ * provider, base_url, api_key presence, and api_mode settings.+ *+ * Also provides provider resolution logic that merges explicit config,+ * Hermes config detection, and model-name prefix inference.+ */++import { readFile } from "node:fs/promises";+import { join } from "node:path";+import { homedir } from "node:os";+import { MODEL_PREFIX_PROVIDER_HINTS, VALID_PROVIDERS } from "../shared/constants.js";++export interface DetectedModel {+ /** Model name from config (e.g. "gpt-5.4", "anthropic/claude-sonnet-4") */+ model: string;+ /** Provider name from config (e.g. "copilot", "zai"). May be empty. */+ provider: string;+ /** Base URL override from config (e.g. "https://api.githubcopilot.com"). May be empty. */+ baseUrl: string;+ /** Whether Hermes config includes a non-empty API key. */+ hasApiKey: boolean;+ /** API mode from config (e.g. "chat_completions", "codex_responses"). May be empty. */+ apiMode: string;+ /** Where the detection came from */+ source: "config";+}++/**+ * Read the Hermes config file and extract the default model config.+ */+export async function detectModel(+ configPath?: string,+): Promise<DetectedModel | null> {+ const filePath = configPath ?? join(homedir(), ".hermes", "config.yaml");++ let content: string;+ try {+ content = await readFile(filePath, "utf-8");+ } catch {+ return null;+ }++ return parseModelFromConfig(content);+}++/**+ * Parse model.default, model.provider, model.base_url, model.api_key, and model.api_mode+ * from raw YAML content. Uses simple regex parsing to avoid a YAML dependency.+ */+export function parseModelFromConfig(content: string): DetectedModel | null {+ const lines = content.split("\n");+ let model = "";+ let provider = "";+ let baseUrl = "";+ let hasApiKey = false;+ let apiMode = "";+ let inModelSection = false;+ let modelSectionIndent = 0;++ for (const line of lines) {+ const trimmed = line.trimEnd();+ const indent = line.length - line.trimStart().length;++ // Track model: section (indent 0)+ if (/^model:\s*$/.test(trimmed) && indent === 0) {+ inModelSection = true;+ modelSectionIndent = 0;+ continue;+ }++ // We left the model section if indent drops back to the section level or below+ if (inModelSection && indent <= modelSectionIndent && trimmed && !trimmed.startsWith("#")) {+ inModelSection = false;+ }++ if (inModelSection) {+ const match = trimmed.match(/^\s*(\w+)\s*:\s*(.+)$/);+ if (match) {+ const key = match[1];+ const val = match[2].trim().replace(/#.*$/, "").trim().replace(/^['"]|['"]$/g, "");+ if (key === "default") model = val;+ if (key === "provider") provider = val;+ if (key === "base_url") baseUrl = val;+ if (key === "api_key") hasApiKey = val.length > 0;+ if (key === "api_mode") apiMode = val;+ }+ }+ }++ if (!model) return null;++ return { model, provider, baseUrl, hasApiKey, apiMode, source: "config" };+}++/**+ * Infer a provider from the model name using prefix-based hints.+ *+ * For example:+ * "gpt-5.4" → "copilot"+ * "claude-sonnet-4" → "anthropic"+ * "glm-5-turbo" → "zai"+ *+ * Returns undefined if no hint matches (caller should fall back to "auto").+ */+export function inferProviderFromModel(model: string): string | undefined {+ const lower = model.toLowerCase();++ // Strip provider/ prefix if present (e.g. "anthropic/claude-sonnet-4")+ const bareName = lower.includes("/") ? lower.split("/").pop()! : lower;++ for (const [prefix, hint] of MODEL_PREFIX_PROVIDER_HINTS) {+ if (bareName.startsWith(prefix)) {+ return hint;+ }+ }++ return undefined;+}++/**+ * Resolve the correct provider for a model, using a priority chain:+ *+ * 1. Explicit provider from adapterConfig (highest priority — user override)+ * 2. Provider from Hermes config file — ONLY if the config model matches+ * the requested model (otherwise the config provider is for a different model)+ * 3. If Hermes config matches the requested model but uses runtime settings that+ * the adapter cannot represent directly, return "auto" and let Hermes resolve it itself+ * 4. Provider inferred from model name prefix+ * 5. "auto" (let Hermes figure it out — lowest priority)+ *+ * Always returns a valid provider string.+ * The `resolvedFrom` field indicates which source was used, useful for logging.+ */+export function resolveProvider(options: {+ /** Explicit provider from adapterConfig (user override) */+ explicitProvider?: string | null;+ /** Provider detected from Hermes config file */+ detectedProvider?: string;+ /** Model name from Hermes config file (to check consistency) */+ detectedModel?: string;+ /** Base URL detected from Hermes config file */+ detectedBaseUrl?: string;+ /** Whether Hermes config includes a non-empty API key */+ detectedHasApiKey?: boolean;+ /** API mode detected from Hermes config file */+ detectedApiMode?: string;+ /** Model name to infer from if no explicit/detected provider */+ model?: string;+}): { provider: string; resolvedFrom: string } {+ const {+ explicitProvider,+ detectedProvider,+ detectedModel,+ detectedBaseUrl,+ detectedHasApiKey,+ detectedApiMode,+ model,+ } = options;++ // 1. Explicit provider from adapterConfig — user override, always wins+ if (explicitProvider && (VALID_PROVIDERS as readonly string[]).includes(explicitProvider)) {+ return { provider: explicitProvider, resolvedFrom: "adapterConfig" };+ }++ const supportedProviders = VALID_PROVIDERS as readonly string[];+ const configMatchesRequestedModel =+ !!detectedModel &&+ !!model &&+ detectedModel.toLowerCase() === model.toLowerCase();++ // 2. Provider from Hermes config file — but ONLY if the config model matches+ // the requested model. Otherwise the config provider is for a different model+ // and would cause exactly the kind of routing bug we're fixing.+ if (+ configMatchesRequestedModel &&+ !!detectedProvider &&+ supportedProviders.includes(detectedProvider)+ ) {+ return { provider: detectedProvider, resolvedFrom: "hermesConfig" };+ }++ const hasRuntimeSignals = !!detectedBaseUrl || !!detectedHasApiKey || !!detectedApiMode;++ // 3a. Matching Hermes config with an unsupported provider (for example "custom")+ // should not fall through to model-name inference, because that can route to+ // the wrong provider entirely. Defer back to Hermes's own runtime resolution.+ if (configMatchesRequestedModel && !!detectedProvider && !supportedProviders.includes(detectedProvider)) {+ return {+ provider: "auto",+ resolvedFrom: `hermesConfigUnsupported:${detectedProvider}`,+ };+ }++ // 3b. Matching Hermes config may omit provider entirely while still specifying+ // enough runtime information (base_url, api_key, api_mode) for Hermes itself.+ // In that case, also defer to Hermes instead of doing a wrong prefix inference.+ if (configMatchesRequestedModel && !detectedProvider && hasRuntimeSignals) {+ return {+ provider: "auto",+ resolvedFrom: "hermesConfigRuntime",+ };+ }++ // 4. Infer from model name prefix+ if (model) {+ const inferred = inferProviderFromModel(model);+ if (inferred) {+ return { provider: inferred, resolvedFrom: "modelInference" };+ }+ }++ // 5. Let Hermes auto-detect+ return { provider: "auto", resolvedFrom: "auto" };+}diff --git a/packages/adapters/hermes/src/server/execute.ts b/packages/adapters/hermes/src/server/execute.tsnew file mode 100644index 0000000000..ae85c29857--- /dev/null+++ b/packages/adapters/hermes/src/server/execute.ts@@ -0,0 +1,584 @@+/**+ * Server-side execution logic for the Hermes Agent adapter.+ *+ * Spawns `hermes chat -q "..." -Q` as a child process, streams output,+ * and returns structured results to Paperclip.+ *+ * Verified CLI flags (hermes chat):+ * -q/--query single query (non-interactive)+ * -Q/--quiet quiet mode (no banner/spinner, only response + session_id)+ * -m/--model model name (e.g. anthropic/claude-sonnet-4)+ * -t/--toolsets comma-separated toolsets to enable+ * --provider inference provider (auto, openrouter, nous, etc.)+ * -r/--resume resume session by ID+ * -w/--worktree isolated git worktree+ * -v/--verbose verbose output+ * --checkpoints filesystem checkpoints+ * --yolo bypass dangerous-command approval prompts (agents have no TTY)+ * --source session source tag for filtering+ */++import fs from "node:fs/promises";+import path from "node:path";++import type {+ AdapterExecutionContext,+ AdapterExecutionResult,+ UsageSummary,+} from "@paperclipai/adapter-utils";++import {+ runChildProcess,+ buildPaperclipEnv,+ renderTemplate,+ ensureAbsoluteDirectory,+ DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,+ joinPromptSections,+ renderPaperclipWakePrompt,+ stringifyPaperclipWakePayload,+} from "@paperclipai/adapter-utils/server-utils";++import {+ HERMES_CLI,+ DEFAULT_TIMEOUT_SEC,+ DEFAULT_GRACE_SEC,+ DEFAULT_MODEL,+ VALID_PROVIDERS,+} from "../shared/constants.js";++import {+ detectModel,+ resolveProvider,+} from "./detect-model.js";++// ---------------------------------------------------------------------------+// Config helpers+// ---------------------------------------------------------------------------++function cfgString(v: unknown): string | undefined {+ return typeof v === "string" && v.length > 0 ? v : undefined;+}+function cfgNumber(v: unknown): number | undefined {+ return typeof v === "number" ? v : undefined;+}+function cfgBoolean(v: unknown): boolean | undefined {+ return typeof v === "boolean" ? v : undefined;+}+function cfgStringArray(v: unknown): string[] | undefined {+ return Array.isArray(v) && v.every((i) => typeof i === "string")+ ? (v as string[])+ : undefined;+}++export function resolveHermesCommand(config: Record<string, unknown>): string {+ return cfgString(config.hermesCommand) || cfgString(config.command) || HERMES_CLI;+}++// ---------------------------------------------------------------------------+// Wake-up prompt builder+// ---------------------------------------------------------------------------++const HERMES_DEFAULT_PROMPT_TEMPLATE = [+ 'You are "{{agent.name}}", an AI agent employee in a Paperclip-managed company.',+ "",+ "Paperclip runtime identity:",+ "- Agent ID: {{agent.id}}",+ "- Company ID: {{agent.companyId}}",+ "- Run ID: {{run.id}}",+ "- API base: {{paperclipApiUrl}}",+ "",+ "Paperclip API guidance:",+ "- Use `curl` from the terminal for Paperclip API calls; browser/web extraction tools may not reach localhost.",+ "- Use `$PAPERCLIP_API_URL`, `$PAPERCLIP_API_KEY`, and `$PAPERCLIP_RUN_ID`; do not hard-code local ports or copy secrets into comments.",+ "- Displayed command logs may redact secrets; rely on environment variables instead of printed token values.",+ "- Include `-H \"Authorization: Bearer $PAPERCLIP_API_KEY\"` on API requests.",+ "- Include `-H \"X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID\"` on mutating issue requests.",+ "- For multiline comments or status updates, preserve newlines with `jq --arg` or a heredoc-fed helper rather than hand-escaping JSON.",+ "",+ "Safe multiline update pattern:",+ "```bash",+ "api=\"${PAPERCLIP_API_URL%/}\"",+ "case \"$api\" in */api) ;; *) api=\"$api/api\" ;; esac",+ "",+ "body=$(cat <<'MD'",+ "Summary line",+ "",+ "- Detail one",+ "- Detail two",+ "MD",+ ")",+ "jq -n --arg status done --arg comment \"$body\" '{status:$status, comment:$comment}' | \\",+ " curl -sS -X PATCH \"$api/issues/{{context.issueId}}\" \\",+ " -H \"Authorization: Bearer $PAPERCLIP_API_KEY\" \\",+ " -H \"X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID\" \\",+ " -H \"Content-Type: application/json\" \\",+ " --data-binary @-",+ "```",+ "",+ DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE,+].join("\n");++function renderConditionalSections(template: string, vars: Record<string, unknown>): string {+ const isTruthy = (key: string) => {+ if (key === "noTask") return !vars.taskId;+ const value = vars[key];+ if (Array.isArray(value)) return value.length > 0;+ return Boolean(value);+ };+ return template.replace(+ /\{\{#([a-zA-Z0-9_.-]+)\}\}([\s\S]*?)\{\{\/\1\}\}/g,+ (_match, key: string, body: string) => (isTruthy(key) ? body : ""),+ );+}++export function buildPrompt(+ ctx: AdapterExecutionContext,+ config: Record<string, unknown>,+ options: { resumedSession?: boolean } = {},+): string {+ const template = cfgString(config.promptTemplate) || HERMES_DEFAULT_PROMPT_TEMPLATE;++ const context = (ctx as any).context || {};+ const taskId = cfgString(context.taskId) || cfgString(context.issueId) || cfgString(ctx.config?.taskId);+ const taskTitle = cfgString(context.taskTitle) || cfgString(ctx.config?.taskTitle) || "";+ const taskBody = cfgString(context.taskBody) || cfgString(ctx.config?.taskBody) || "";+ const commentId = cfgString(context.commentId) || cfgString(context.wakeCommentId) || cfgString(ctx.config?.commentId) || "";+ const wakeReason = cfgString(context.wakeReason) || cfgString(ctx.config?.wakeReason) || "";+ const agentName = ctx.agent?.name || "Hermes Agent";+ const companyName = cfgString(context.companyName) || cfgString(ctx.config?.companyName) || "";+ const projectName = cfgString(context.projectName) || cfgString(ctx.config?.projectName) || "";++ // Build API URL — ensure it has the /api path+ let paperclipApiUrl =+ cfgString(config.paperclipApiUrl) ||+ process.env.PAPERCLIP_API_URL ||+ "http://127.0.0.1:3100/api";+ // Ensure /api suffix+ if (!paperclipApiUrl.endsWith("/api")) {+ paperclipApiUrl = paperclipApiUrl.replace(/\/+$/, "") + "/api";+ }++ const wakePrompt = renderPaperclipWakePrompt(context.paperclipWake, {+ resumedSession: options.resumedSession === true,+ });+ const paperclipTaskMarkdown = cfgString(context.paperclipTaskMarkdown)?.trim() || "";+ const sessionHandoffMarkdown = cfgString(context.paperclipSessionHandoffMarkdown)?.trim() || "";+ const wakePayloadJson = stringifyPaperclipWakePayload(context.paperclipWake) || "";++ const vars: Record<string, unknown> = {+ agentId: ctx.agent?.id || "",+ agentName,+ companyId: ctx.agent?.companyId || "",+ companyName,+ runId: ctx.runId || "",+ agent: ctx.agent || {},+ company: { id: ctx.agent?.companyId || "", name: companyName },+ run: { id: ctx.runId || "", source: "on_demand" },+ context,+ taskId: taskId || "",+ taskTitle,+ taskBody,+ commentId,+ wakeReason,+ projectName,+ paperclipApiUrl,+ paperclipWakePrompt: wakePrompt,+ paperclipTaskMarkdown,+ taskContext: paperclipTaskMarkdown,+ paperclipWakeJson: wakePayloadJson,+ wakePayloadJson,+ paperclipApiKeyEnv: "PAPERCLIP_API_KEY",+ paperclipRunIdEnv: "PAPERCLIP_RUN_ID",+ };++ const rendered = renderTemplate(renderConditionalSections(template, vars), vars);+ return joinPromptSections([+ wakePrompt,+ sessionHandoffMarkdown,+ paperclipTaskMarkdown,+ rendered,+ ]);+}++// ---------------------------------------------------------------------------+// Output parsing+// ---------------------------------------------------------------------------++/** Regex to extract session ID from Hermes quiet-mode output: "session_id: <id>" */+const SESSION_ID_REGEX = /^session_id:\s*(\S+)/m;++/** Regex for legacy session output format */+const SESSION_ID_REGEX_LEGACY = /session[_ ](?:id|saved)[:\s]+([a-zA-Z0-9_-]+)/i;++/** Regex to extract token usage from Hermes output. */+const TOKEN_USAGE_REGEX =+ /tokens?[:\s]+(\d+)\s*(?:input|in)\b.*?(\d+)\s*(?:output|out)\b/i;++/** Regex to extract cost from Hermes output. */+const COST_REGEX = /(?:cost|spent)[:\s]*\$?([\d.]+)/i;++interface ParsedOutput {+ sessionId?: string;+ response?: string;+ usage?: UsageSummary;+ costUsd?: number;+ errorMessage?: string;+}++// ---------------------------------------------------------------------------+// Response cleaning+// ---------------------------------------------------------------------------++/** Strip noise lines from a Hermes response (tool output, system messages, etc.) */+function cleanResponse(raw: string): string {+ return raw+ .split("\n")+ .filter((line) => {+ const t = line.trim();+ if (!t) return true; // keep blank lines for paragraph separation+ if (t.startsWith("[tool]") || t.startsWith("[hermes]") || t.startsWith("[paperclip]")) return false;+ if (t.startsWith("session_id:")) return false;+ if (/^\[\d{4}-\d{2}-\d{2}T/.test(t)) return false;+ if (/^\[done\]\s*┊/.test(t)) return false;+ if (/^┊\s*[\p{Emoji_Presentation}]/u.test(t) && !/^┊\s*💬/.test(t)) return false;+ if (/^\p{Emoji_Presentation}\s*(Completed|Running|Error)?\s*$/u.test(t)) return false;+ return true;+ })+ .map((line) => {+ let t = line.replace(/^[\s]*┊\s*💬\s*/, "").trim();+ t = t.replace(/^\[done\]\s*/, "").trim();+ return t;+ })+ .join("\n")+ .replace(/\n{3,}/g, "\n\n")+ .trim();+}++// ---------------------------------------------------------------------------+// Output parsing+// ---------------------------------------------------------------------------++function parseHermesOutput(stdout: string, stderr: string): ParsedOutput {+ const combined = stdout + "\n" + stderr;+ const result: ParsedOutput = {};++ // In quiet mode, Hermes outputs:+ // <response text>+ //+ // session_id: <id>+ const sessionMatch = stdout.match(SESSION_ID_REGEX);+ if (sessionMatch?.[1]) {+ result.sessionId = sessionMatch?.[1] ?? null;+ // The response is everything before the session_id line+ const sessionLineIdx = stdout.lastIndexOf("\nsession_id:");+ if (sessionLineIdx > 0) {+ result.response = cleanResponse(stdout.slice(0, sessionLineIdx));+ }+ } else {+ // Legacy format (non-quiet mode)+ const legacyMatch = combined.match(SESSION_ID_REGEX_LEGACY);+ if (legacyMatch?.[1]) {+ result.sessionId = legacyMatch?.[1] ?? null;+ }+ // In non-quiet mode, extract clean response from stdout by+ // filtering out tool lines, system messages, and noise+ const cleaned = cleanResponse(stdout);+ if (cleaned.length > 0) {+ result.response = cleaned;+ }+ }++ // Extract token usage+ const usageMatch = combined.match(TOKEN_USAGE_REGEX);+ if (usageMatch) {+ result.usage = {+ inputTokens: parseInt(usageMatch[1], 10) || 0,+ outputTokens: parseInt(usageMatch[2], 10) || 0,+ };+ }++ // Extract cost+ const costMatch = combined.match(COST_REGEX);+ if (costMatch?.[1]) {+ result.costUsd = parseFloat(costMatch[1]);+ }++ // Check for error patterns in stderr+ if (stderr.trim()) {+ const errorLines = stderr+ .split("\n")+ .filter((line) => /error|exception|traceback|failed/i.test(line))+ .filter((line) => !/INFO|DEBUG|warn/i.test(line)); // skip log-level noise+ if (errorLines.length > 0) {+ result.errorMessage = errorLines.slice(0, 5).join("\n");+ }+ }++ return result;+}++// ---------------------------------------------------------------------------+// Main execute+// ---------------------------------------------------------------------------++export async function execute(+ ctx: AdapterExecutionContext,+): Promise<AdapterExecutionResult> {+ const config = (ctx.config ?? ctx.agent?.adapterConfig ?? {}) as Record<string, unknown>;++ // ── Resolve configuration ──────────────────────────────────────────────+ const hermesCmd = resolveHermesCommand(config);+ const model = cfgString(config.model) || DEFAULT_MODEL;+ const timeoutSec = cfgNumber(config.timeoutSec) || DEFAULT_TIMEOUT_SEC;+ const graceSec = cfgNumber(config.graceSec) || DEFAULT_GRACE_SEC;+ const maxTurns = cfgNumber(config.maxTurnsPerRun);+ const toolsets = cfgString(config.toolsets) || cfgStringArray(config.enabledToolsets)?.join(",");+ const extraArgs = cfgStringArray(config.extraArgs);+ const persistSession = cfgBoolean(config.persistSession) !== false;+ const worktreeMode = cfgBoolean(config.worktreeMode) === true;+ const checkpoints = cfgBoolean(config.checkpoints) === true;+ const prevSessionId = cfgString(+ (ctx.runtime?.sessionParams as Record<string, unknown> | null)?.sessionId,+ );++ // ── Resolve provider (defense in depth) ────────────────────────────────+ // Priority chain:+ // 1. Explicit provider in adapterConfig (user override)+ // 2. Provider from ~/.hermes/config.yaml (detected at runtime)+ // 3. Provider inferred from model name prefix+ // 4. "auto" (let Hermes decide)+ //+ // This ensures that even if the agent was created before provider tracking+ // was added, or if the model was changed without updating provider, the+ // correct provider is still used.+ let detectedConfig: Awaited<ReturnType<typeof detectModel>> | null = null;+ const explicitProvider = cfgString(config.provider);++ if (!explicitProvider) {+ try {+ detectedConfig = await detectModel();+ } catch {+ // Non-fatal — detection failure shouldn't block execution+ }+ }++ const { provider: resolvedProvider, resolvedFrom } = resolveProvider({+ explicitProvider,+ detectedProvider: detectedConfig?.provider,+ detectedModel: detectedConfig?.model,+ detectedBaseUrl: detectedConfig?.baseUrl,+ detectedHasApiKey: detectedConfig?.hasApiKey,+ detectedApiMode: detectedConfig?.apiMode,+ model,+ });++ // ── Load agent instructions file (Paperclip instruction bundles) ──────+ // Paperclip can materialize managed instructions into instructionsFilePath;+ // when present, inject that bundle into the Hermes prompt.+ const instructionsFilePath = cfgString(config.instructionsFilePath);+ let agentInstructions = "";+ if (instructionsFilePath) {+ try {+ agentInstructions = await fs.readFile(instructionsFilePath, "utf-8");+ const loadedInstructionsLength = agentInstructions.length;+ const instructionsFileDir = path.dirname(instructionsFilePath);+ agentInstructions += `\nThe above agent instructions were loaded from ${instructionsFilePath}. Resolve any relative file references from ${instructionsFileDir}/.`;+ await ctx.onLog(+ "stdout",+ `[hermes] Loaded agent instructions from ${instructionsFilePath} (${loadedInstructionsLength} chars)\n`,+ );+ } catch (err) {+ const reason = err instanceof Error ? err.message : String(err);+ // Non-fatal: log to stdout with an explicit "Warning:" prefix so the+ // Paperclip UI doesn't render this as a red error (stderr output is+ // surfaced as an error signal even when execution continues).+ await ctx.onLog(+ "stdout",+ `[hermes] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`,+ );+ }+ }++ // ── Build prompt ───────────────────────────────────────────────────────+ let prompt = buildPrompt(ctx, config, { resumedSession: Boolean(prevSessionId) });+ if (agentInstructions) {+ prompt = agentInstructions + "\n\n---\n\n" + prompt;+ }++ // ── Build command args ─────────────────────────────────────────────────+ // Use -Q (quiet) to get clean output: just response + session_id line+ const useQuiet = cfgBoolean(config.quiet) === true; // default false+ const args: string[] = ["chat", "-q", prompt];+ if (useQuiet) args.push("-Q");++ if (model) {+ args.push("-m", model);+ }++ // Always pass --provider when we have a resolved one (not "auto").+ // "auto" means Hermes will decide on its own — no need to pass it.+ if (resolvedProvider !== "auto") {+ args.push("--provider", resolvedProvider);+ }++ if (toolsets) {+ args.push("-t", toolsets);+ }++ if (maxTurns && maxTurns > 0) {+ args.push("--max-turns", String(maxTurns));+ }++ if (worktreeMode) args.push("-w");+ if (checkpoints) args.push("--checkpoints");+ if (cfgBoolean(config.verbose) === true) args.push("-v");++ // Tag sessions as "tool" source so they don't clutter the user's session history.+ // Requires hermes-agent >= PR #3255 (feat/session-source-tag).+ args.push("--source", "tool");++ // Bypass Hermes dangerous-command approval prompts.+ // Paperclip agents run as non-interactive subprocesses with no TTY,+ // so approval prompts would always timeout and deny legitimate commands+ // (curl, python3 -c, etc.). Agents operate in a sandbox — the approval+ // system is designed for human-attended interactive sessions.+ args.push("--yolo");++ if (persistSession && prevSessionId) {+ args.push("--resume", prevSessionId);+ }++ if (extraArgs?.length) {+ args.push(...extraArgs);+ }++ // ── Build environment ──────────────────────────────────────────────────+ const userEnv = config.env as Record<string, string> | undefined;+ const env: Record<string, string> = {+ ...(process.env as Record<string, string>),+ ...(userEnv && typeof userEnv === "object" ? userEnv : {}),+ ...buildPaperclipEnv(ctx.agent),+ };++ if (ctx.runId) env.PAPERCLIP_RUN_ID = ctx.runId;++ // BUG FIX: Inject authToken as PAPERCLIP_API_KEY (matches adapter-claude-local behavior)+ if ((ctx as any).authToken) env.PAPERCLIP_API_KEY = (ctx as any).authToken;++ // BUG FIX: Read task context from ctx.context (wake context), not ctx.config (adapter config)+ const ctxContext = (ctx as any).context || {};+ const envTaskId = cfgString(ctxContext.taskId) || cfgString(ctxContext.issueId) || cfgString(ctx.config?.taskId);+ if (envTaskId) env.PAPERCLIP_TASK_ID = envTaskId;+ const envWakeReason = cfgString(ctxContext.wakeReason) || cfgString(ctx.config?.wakeReason);+ if (envWakeReason) env.PAPERCLIP_WAKE_REASON = envWakeReason;+ const envCommentId = cfgString(ctxContext.commentId) || cfgString(ctxContext.wakeCommentId) || cfgString(ctx.config?.commentId);+ if (envCommentId) env.PAPERCLIP_WAKE_COMMENT_ID = envCommentId;+ const wakePayloadJson = stringifyPaperclipWakePayload(ctxContext.paperclipWake);+ if (wakePayloadJson) env.PAPERCLIP_WAKE_PAYLOAD_JSON = wakePayloadJson;++ // ── Resolve working directory ──────────────────────────────────────────+ const cwd =+ cfgString(config.cwd) || cfgString(ctx.config?.workspaceDir) || ".";+ try {+ await ensureAbsoluteDirectory(cwd);+ } catch {+ // Non-fatal+ }++ // ── Log start ──────────────────────────────────────────────────────────+ await ctx.onLog(+ "stdout",+ `[hermes] Starting Hermes Agent (model=${model}, provider=${resolvedProvider} [${resolvedFrom}], timeout=${timeoutSec}s${maxTurns ? `, max_turns=${maxTurns}` : ""})\n`,+ );+ if (prevSessionId) {+ await ctx.onLog(+ "stdout",+ `[hermes] Resuming session: ${prevSessionId}\n`,+ );+ }++ // ── Execute ────────────────────────────────────────────────────────────+ // Hermes writes non-error noise to stderr (MCP init, INFO logs, etc).+ // Paperclip renders all stderr as red/error in the UI.+ // Wrap onLog to reclassify benign stderr lines as stdout.+ const wrappedOnLog = async (stream: "stdout" | "stderr", chunk: string) => {+ if (stream === "stderr") {+ const trimmed = chunk.trimEnd();+ // Benign patterns that should NOT appear as errors:+ // - Structured log lines: [timestamp] INFO/DEBUG/WARN: ...+ // - MCP server registration messages+ // - Python import/site noise+ const isBenign = /^\[?\d{4}[-/]\d{2}[-/]\d{2}T/.test(trimmed) || // structured timestamps+ /^[A-Z]+:\s+(INFO|DEBUG|WARN|WARNING)\b/.test(trimmed) || // log levels+ /Successfully registered all tools/.test(trimmed) ||+ /MCP [Ss]erver/.test(trimmed) ||+ /tool registered successfully/.test(trimmed) ||+ /Application initialized/.test(trimmed);+ if (isBenign) {+ return ctx.onLog("stdout", chunk);+ }+ }+ return ctx.onLog(stream, chunk);+ };++ const result = await runChildProcess(ctx.runId, hermesCmd, args, {+ cwd,+ env,+ timeoutSec,+ graceSec,+ onLog: wrappedOnLog,+ });++ // ── Parse output ───────────────────────────────────────────────────────+ const parsed = parseHermesOutput(result.stdout || "", result.stderr || "");++ await ctx.onLog(+ "stdout",+ `[hermes] Exit code: ${result.exitCode ?? "null"}, timed out: ${result.timedOut}\n`,+ );+ if (parsed.sessionId) {+ await ctx.onLog("stdout", `[hermes] Session: ${parsed.sessionId}\n`);+ }++ // ── Build result ───────────────────────────────────────────────────────+ const executionResult: AdapterExecutionResult = {+ exitCode: result.exitCode,+ signal: result.signal,+ timedOut: result.timedOut,+ provider: resolvedProvider,+ model,+ };++ if (parsed.errorMessage) {+ executionResult.errorMessage = parsed.errorMessage;+ }++ if (parsed.usage) {+ executionResult.usage = parsed.usage;+ }++ if (parsed.costUsd !== undefined) {+ executionResult.costUsd = parsed.costUsd;+ }++ // Summary from agent response+ if (parsed.response) {+ executionResult.summary = parsed.response.slice(0, 2000);+ }++ // Set resultJson so Paperclip can persist run metadata (used for UI display + auto-comments)+ executionResult.resultJson = {+ result: parsed.response || "",+ session_id: parsed.sessionId || null,+ usage: parsed.usage || null,+ cost_usd: parsed.costUsd ?? null,+ };++ // Store session ID for next run+ if (persistSession && parsed.sessionId) {+ executionResult.sessionParams = { sessionId: parsed.sessionId };+ executionResult.sessionDisplayId = parsed.sessionId.slice(0, 16);+ }++ return executionResult;+}diff --git a/packages/adapters/hermes/src/server/index.ts b/packages/adapters/hermes/src/server/index.tsnew file mode 100644index 0000000000..2382374d46--- /dev/null+++ b/packages/adapters/hermes/src/server/index.ts@@ -0,0 +1,49 @@+/**+ * Server-side adapter module exports.+ */++export { execute } from "./execute.js";+export { testEnvironment } from "./test.js";+export { detectModel, parseModelFromConfig, resolveProvider, inferProviderFromModel } from "./detect-model.js";+export { getConfigSchema } from "./config-schema.js";+export {+ listHermesSkills as listSkills,+ syncHermesSkills as syncSkills,+ resolveHermesDesiredSkillNames as resolveDesiredSkillNames,+} from "./skills.js";++import type { AdapterSessionCodec } from "@paperclipai/adapter-utils";++function readNonEmptyString(value: unknown): string | null {+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;+}++/**+ * Session codec for structured validation and migration of session parameters.+ *+ * Hermes Agent uses a single `sessionId` for cross-heartbeat session continuity+ * via the `--resume` CLI flag. The codec validates and normalizes this field.+ */+export const sessionCodec: AdapterSessionCodec = {+ deserialize(raw: unknown) {+ if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return null;+ const record = raw as Record<string, unknown>;+ const sessionId =+ readNonEmptyString(record.sessionId) ??+ readNonEmptyString(record.session_id);+ if (!sessionId) return null;+ return { sessionId };+ },+ serialize(params: Record<string, unknown> | null) {+ if (!params) return null;+ const sessionId =+ readNonEmptyString(params.sessionId) ??+ readNonEmptyString(params.session_id);+ if (!sessionId) return null;+ return { sessionId };+ },+ getDisplayId(params: Record<string, unknown> | null) {+ if (!params) return null;+ return readNonEmptyString(params.sessionId) ?? readNonEmptyString(params.session_id);+ },+};diff --git a/packages/adapters/hermes/src/server/paperclip-task-bridge.test.ts b/packages/adapters/hermes/src/server/paperclip-task-bridge.test.tsnew file mode 100644index 0000000000..1801407269--- /dev/null+++ b/packages/adapters/hermes/src/server/paperclip-task-bridge.test.ts@@ -0,0 +1,184 @@+import { spawn } from "node:child_process";+import http from "node:http";+import path from "node:path";+import { fileURLToPath } from "node:url";+import { afterEach, beforeEach, describe, expect, it } from "vitest";++const __dirname = path.dirname(fileURLToPath(import.meta.url));+const helperPath = path.resolve(__dirname, "../../skills/paperclip-task-bridge/paperclip-task.mjs");+const apiKey = "pc_test_secret_should_not_print";++type RequestRecord = {+ method: string;+ url: string;+ headers: http.IncomingHttpHeaders;+ body: unknown;+};++function runHelper(args: string[], env: Record<string, string>) {+ return new Promise<{ code: number | null; stdout: string; stderr: string }>((resolve, reject) => {+ const child = spawn(process.execPath, [helperPath, ...args], {+ env: {+ ...process.env,+ ...env,+ },+ stdio: ["ignore", "pipe", "pipe"],+ });+ let stdout = "";+ let stderr = "";+ child.stdout.setEncoding("utf8");+ child.stderr.setEncoding("utf8");+ child.stdout.on("data", (chunk) => {+ stdout += chunk;+ });+ child.stderr.on("data", (chunk) => {+ stderr += chunk;+ });+ child.on("error", reject);+ child.on("close", (code) => resolve({ code, stdout, stderr }));+ });+}++describe("paperclip-task-bridge helper", () => {+ let server: http.Server;+ let baseUrl: string;+ let requests: RequestRecord[];++ beforeEach(async () => {+ requests = [];+ server = http.createServer(async (req, res) => {+ let raw = "";+ req.setEncoding("utf8");+ for await (const chunk of req) raw += chunk;+ const body = raw ? JSON.parse(raw) : null;+ requests.push({+ method: req.method ?? "GET",+ url: req.url ?? "/",+ headers: req.headers,+ body,+ });++ res.setHeader("Content-Type", "application/json");+ if (req.headers.authorization !== `Bearer ${apiKey}`) {+ res.statusCode = 401;+ res.end(JSON.stringify({ error: "bad auth" }));+ return;+ }+ if (req.method === "GET" && req.url === "/api/agents/me") {+ res.end(JSON.stringify({ id: "11111111-1111-4111-8111-111111111111", companyId: "22222222-2222-4222-8222-222222222222" }));+ return;+ }+ if (req.method === "GET" && req.url === "/api/agents/me/inbox-lite") {+ res.end(JSON.stringify([+ {+ id: "33333333-3333-4333-8333-333333333333",+ identifier: "PAP-123",+ title: "Existing task",+ status: "todo",+ priority: "medium",+ assigneeAgentId: "11111111-1111-4111-8111-111111111111",+ updatedAt: "2026-06-26T00:00:00.000Z",+ },+ ]));+ return;+ }+ if (req.method === "POST" && req.url === "/api/companies/22222222-2222-4222-8222-222222222222/issues") {+ res.statusCode = 201;+ res.end(JSON.stringify({+ id: "44444444-4444-4444-8444-444444444444",+ identifier: "PAP-124",+ title: body.title,+ status: body.status ?? "todo",+ priority: body.priority,+ assigneeAgentId: body.assigneeAgentId ?? null,+ }));+ return;+ }+ if (req.method === "POST" && req.url === "/api/issues/PAP-123/comments") {+ res.statusCode = 201;+ res.end(JSON.stringify({+ id: "55555555-5555-4555-8555-555555555555",+ issueId: "33333333-3333-4333-8333-333333333333",+ authorType: "agent",+ authorAgentId: "11111111-1111-4111-8111-111111111111",+ createdAt: "2026-06-26T00:00:00.000Z",+ }));+ return;+ }+ if (req.method === "PATCH" && req.url === "/api/issues/PAP-123") {+ res.end(JSON.stringify({+ id: "33333333-3333-4333-8333-333333333333",+ identifier: "PAP-123",+ title: "Existing task",+ status: body.status,+ priority: "medium",+ }));+ return;+ }+ res.statusCode = 404;+ res.end(JSON.stringify({ error: "not found" }));+ });++ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));+ const address = server.address();+ if (!address || typeof address === "string") throw new Error("missing server address");+ baseUrl = `http://127.0.0.1:${address.port}/api`;+ });++ afterEach(async () => {+ await new Promise<void>((resolve, reject) => {+ server.close((err) => (err ? reject(err) : resolve()));+ });+ });++ function env() {+ return {+ PAPERCLIP_API_URL: baseUrl,+ PAPERCLIP_BRIDGE_API_KEY: apiKey,+ PAPERCLIP_COMPANY_ID: "22222222-2222-4222-8222-222222222222",+ PAPERCLIP_AGENT_ID: "11111111-1111-4111-8111-111111111111",+ PAPERCLIP_RUN_ID: "66666666-6666-4666-8666-666666666666",+ };+ }++ it("lists assigned tasks without printing credentials", async () => {+ const result = await runHelper(["list-assigned"], env());++ expect(result.code).toBe(0);+ expect(result.stdout).toContain('"command": "list-assigned"');+ expect(result.stdout).toContain('"identifier": "PAP-123"');+ expect(result.stdout).not.toContain(apiKey);+ expect(result.stderr).not.toContain(apiKey);+ expect(requests.some((request) => request.url === "/api/agents/me/inbox-lite")).toBe(true);+ });++ it("creates tasks assigned to the authenticated agent by default", async () => {+ const result = await runHelper(["create-task", "--title", "Bridge task", "--description", "Created from Hermes"], env());++ expect(result.code).toBe(0);+ expect(result.stdout).toContain('"identifier": "PAP-124"');+ const createRequest = requests.find((request) => request.method === "POST" && request.url.includes("/companies/"));+ expect(createRequest?.headers["x-paperclip-run-id"]).toBe("66666666-6666-4666-8666-666666666666");+ expect(createRequest?.body).toMatchObject({+ title: "Bridge task",+ description: "Created from Hermes",+ priority: "medium",+ workMode: "standard",+ assigneeAgentId: "11111111-1111-4111-8111-111111111111",+ });+ expect(result.stdout).not.toContain(apiKey);+ });++ it("comments and updates status through direct issue identifier routes", async () => {+ const comment = await runHelper(["comment", "--issue", "PAP-123", "--body", "Progress from Hermes"], env());+ const update = await runHelper(["update-status", "--issue", "PAP-123", "--status", "in_review", "--comment", "Ready"], env());++ expect(comment.code).toBe(0);+ expect(update.code).toBe(0);+ const commentRequest = requests.find((request) => request.method === "POST" && request.url.includes("/comments"));+ const patchRequest = requests.find((request) => request.method === "PATCH");+ expect(commentRequest?.body).toMatchObject({ body: "Progress from Hermes" });+ expect(patchRequest?.body).toMatchObject({ status: "in_review", comment: "Ready" });+ expect(comment.stdout + update.stdout).not.toContain(apiKey);+ });+});diff --git a/packages/adapters/hermes/src/server/prompt-rendering.test.ts b/packages/adapters/hermes/src/server/prompt-rendering.test.tsnew file mode 100644index 0000000000..1a5d1c9a8a--- /dev/null+++ b/packages/adapters/hermes/src/server/prompt-rendering.test.ts@@ -0,0 +1,248 @@+import { expect, test } from "vitest";++import { buildPrompt } from "./execute.js";++function baseContext(overrides: Record<string, unknown> = {}) {+ return {+ agent: {+ id: "agent-1",+ name: "Hermes Engineer",+ companyId: "company-1",+ },+ runId: "run-1",+ config: {},+ context: {+ issueId: "issue-1",+ paperclipWake: {+ reason: "issue_assigned",+ issue: {+ id: "issue-1",+ identifier: "PAP-3404",+ title: "Plan the Hermes prompt update",+ status: "in_progress",+ priority: "medium",+ workMode: "planning",+ },+ checkedOutByHarness: true,+ commentWindow: { requestedCount: 0, includedCount: 0, missingCount: 0 },+ comments: [],+ fallbackFetchNeeded: false,+ },+ paperclipTaskMarkdown: [+ "Paperclip task context:",+ '- Issue: "PAP-3404"',+ '- Title: "Plan the Hermes prompt update"',+ "",+ "Planning mode directive:",+ "Make the plan only. Do not write code or perform implementation work.",+ "",+ "Issue description:",+ "```text",+ "Use the wake payload as runtime authority.",+ "```",+ ].join("\n"),+ ...overrides,+ },+ } as any;+}++test("renders standard assignment wake with task authority and no backlog discovery guidance", () => {+ const prompt = buildPrompt(baseContext({+ paperclipWake: {+ reason: "issue_assigned",+ issue: {+ id: "issue-1",+ identifier: "PAP-11750",+ title: "Add Hermes prompt rendering regression tests",+ status: "in_progress",+ priority: "medium",+ workMode: "standard",+ },+ checkedOutByHarness: true,+ commentWindow: { requestedCount: 0, includedCount: 0, missingCount: 0 },+ comments: [],+ fallbackFetchNeeded: false,+ },+ paperclipTaskMarkdown: [+ "Paperclip task context:",+ '- Issue: "PAP-11750"',+ '- Title: "Add Hermes prompt rendering regression tests"',+ "",+ "Issue description:",+ "```text",+ "Add focused unit tests for assignment wake and custom prompt rendering.",+ "```",+ ].join("\n"),+ }), {});++ expect(prompt).toContain("## Paperclip Wake Payload");+ expect(prompt).toContain("- reason: issue_assigned");+ expect(prompt).toContain("- issue: PAP-11750 Add Hermes prompt rendering regression tests");+ expect(prompt).toContain("- issue work mode: standard");+ expect(prompt).toContain("Paperclip task context:");+ expect(prompt).toContain("Add focused unit tests for assignment wake and custom prompt rendering.");+ expect(prompt).toContain("The harness already checked out this issue for the current run.");+ expect(prompt).toContain("clear final disposition");+ expect(prompt).not.toContain("check for unassigned issues");+ expect(prompt).not.toContain("status=backlog");+});++test("renders scoped planning wake authority before the Hermes default workflow", () => {+ const prompt = buildPrompt(baseContext(), {+ paperclipApiUrl: "http://127.0.0.1:3101/api",+ });++ expect(prompt).toContain("## Paperclip Wake Payload");+ expect(prompt).toContain("- issue: PAP-3404 Plan the Hermes prompt update");+ expect(prompt).toContain("- planning directive: Make the plan only. Do not write code or perform implementation work.");+ expect(prompt).toContain("- checkout: already claimed by the harness for this run");+ expect(prompt).toContain("The harness already checked out this issue for the current run.");+ expect(prompt).toContain("Issue description:\n```text\nUse the wake payload as runtime authority.\n```");+ expect(prompt).toContain("clear final disposition");+ expect(prompt).toContain("keep `in_progress` only when a live continuation path exists");+ expect(prompt).not.toContain("check for unassigned issues");+ expect(prompt).not.toContain("status=backlog");+});++test("renders resume deltas instead of full scoped-wake boilerplate when continuing a session", () => {+ const prompt = buildPrompt(baseContext({+ paperclipWake: {+ reason: "issue_commented",+ issue: {+ id: "issue-1",+ identifier: "PAP-11750",+ title: "Add Hermes prompt rendering regression tests",+ status: "in_progress",+ priority: "medium",+ workMode: "standard",+ },+ latestCommentId: "comment-2",+ commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },+ comments: [{ id: "comment-2", body: "Please add the resume-delta case.", createdAt: "2026-06-23T00:00:00.000Z" }],+ fallbackFetchNeeded: false,+ },+ }), {}, { resumedSession: true });++ expect(prompt).toContain("## Paperclip Resume Delta");+ expect(prompt).toContain("You are resuming an existing Paperclip session.");+ expect(prompt).toContain("Focus on the new wake delta below");+ expect(prompt).toContain("Please add the resume-delta case.");+ expect(prompt).toContain("- fallback fetch needed: no");+ expect(prompt).not.toContain("Before generic repo exploration or boilerplate heartbeat updates");+});++test("renders comment wake batch guidance without defaulting to a full-thread refetch", () => {+ const prompt = buildPrompt(baseContext({+ wakeCommentId: "comment-1",+ paperclipWake: {+ reason: "issue_commented",+ issue: {+ id: "issue-1",+ identifier: "PAP-3404",+ title: "Plan the Hermes prompt update",+ status: "in_progress",+ priority: "medium",+ workMode: "standard",+ },+ latestCommentId: "comment-1",+ commentWindow: { requestedCount: 1, includedCount: 1, missingCount: 0 },+ comments: [{ id: "comment-1", body: "Please tighten the prompt.", createdAt: "2026-06-23T00:00:00.000Z" }],+ fallbackFetchNeeded: false,+ },+ }), {});++ expect(prompt).toContain("Use this inline wake data first before refetching the issue thread.");+ expect(prompt).toContain("Only fetch the API thread when `fallbackFetchNeeded` is true");+ expect(prompt).toContain("New comments in order:");+ expect(prompt).toContain("Please tighten the prompt.");+ expect(prompt).toContain("- fallback fetch needed: no");+});++test("renders accepted-plan continuation without authorizing implementation on the planning issue", () => {+ const prompt = buildPrompt(baseContext({+ paperclipWake: {+ reason: "issue_commented",+ issue: {+ id: "issue-1",+ identifier: "PAP-3404",+ title: "Plan the Hermes prompt update",+ status: "in_progress",+ priority: "medium",+ workMode: "planning",+ },+ interactionKind: "request_confirmation",+ interactionStatus: "accepted",+ commentWindow: { requestedCount: 0, includedCount: 0, missingCount: 0 },+ comments: [],+ fallbackFetchNeeded: false,+ },+ }), {});++ expect(prompt).toContain("- planning directive: Create child issues from the approved plan only. Do not write code or perform implementation work on the planning issue.");+ expect(prompt).toContain("- accepted-plan continuation: you may create child implementation issues from the approved plan");+ expect(prompt).toContain("must not start implementation work on the planning issue itself");+ expect(prompt).not.toContain("- planning directive: Make the plan only.");+ expect(prompt).not.toContain("Update the plan only");+});++test("keeps authoritative parent and ancestor context from task markdown", () => {+ const prompt = buildPrompt(baseContext({+ paperclipTaskMarkdown: [+ "Paperclip task context:",+ '- Issue: "PAP-3404"',+ "",+ "Authoritative parent / ancestor context:",+ "- Parent: PAP-11724 Optimize prompt traces (in_progress) [medium]",+ "- Ancestor 2: PAP-11721 Fetch raw traces (done) [medium]",+ ].join("\n"),+ }), {});++ expect(prompt).toContain("Authoritative parent / ancestor context:");+ expect(prompt).toContain("- Parent: PAP-11724 Optimize prompt traces (in_progress) [medium]");+ expect(prompt).not.toContain("check the issue body or comments for references");+});++test("renders safe Paperclip API examples from environment variables with multiline update preservation", () => {+ const prompt = buildPrompt(baseContext(), {+ paperclipApiUrl: "http://paperclip.local/api",+ });++ expect(prompt).toContain("Use `$PAPERCLIP_API_URL`, `$PAPERCLIP_API_KEY`, and `$PAPERCLIP_RUN_ID`");+ expect(prompt).toContain("Displayed command logs may redact secrets");+ expect(prompt).toContain('-H "Authorization: Bearer $PAPERCLIP_API_KEY"');+ expect(prompt).toContain('-H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID"');+ expect(prompt).toContain("body=$(cat <<'MD'");+ expect(prompt).toContain("jq -n --arg status done --arg comment \"$body\"");+ expect(prompt).toContain("--data-binary @-");+ expect(prompt).not.toContain("Authorization: Bearer <");+});++test("preserves custom prompt templates while exposing runtime and wake variables", () => {+ const prompt = buildPrompt(baseContext(), {+ paperclipApiUrl: "http://paperclip.local/api",+ promptTemplate: [+ "CUSTOM TEMPLATE",+ "agent={{agent.name}}",+ "api={{paperclipApiUrl}}",+ "keyEnv={{paperclipApiKeyEnv}}",+ "runEnv={{paperclipRunIdEnv}}",+ "wakePrompt={{paperclipWakePrompt}}",+ "task={{paperclipTaskMarkdown}}",+ "wakeJson={{paperclipWakeJson}}",+ "wake={{wakePayloadJson}}",+ ].join("\n"),+ });++ expect(prompt).toContain("CUSTOM TEMPLATE");+ expect(prompt).toContain("agent=Hermes Engineer");+ expect(prompt).toContain("api=http://paperclip.local/api");+ expect(prompt).toContain("keyEnv=PAPERCLIP_API_KEY");+ expect(prompt).toContain("runEnv=PAPERCLIP_RUN_ID");+ expect(prompt).toContain("wakePrompt=## Paperclip Wake Payload");+ expect(prompt).toContain("task=Paperclip task context:");+ expect(prompt).toContain("wakeJson={\"reason\":\"issue_assigned\"");+ expect(prompt).toContain('"reason":"issue_assigned"');+ expect(prompt).toContain("## Paperclip Wake Payload");+ expect(prompt).toContain("Issue description:\n```text\nUse the wake payload as runtime authority.\n```");+ expect(prompt).not.toContain("Paperclip runtime identity:");+});diff --git a/packages/adapters/hermes/src/server/skills.ts b/packages/adapters/hermes/src/server/skills.tsnew file mode 100644index 0000000000..6a9ea3c0d7--- /dev/null+++ b/packages/adapters/hermes/src/server/skills.ts@@ -0,0 +1,226 @@+import fs from "node:fs/promises";+import os from "node:os";+import path from "node:path";+import type {+ AdapterSkillContext,+ AdapterSkillEntry,+ AdapterSkillSnapshot,+} from "@paperclipai/adapter-utils";+import {+ readPaperclipRuntimeSkillEntries,+ resolvePaperclipDesiredSkillNames,+} from "@paperclipai/adapter-utils/server-utils";+import { fileURLToPath } from "node:url";++const __moduleDir = path.dirname(fileURLToPath(import.meta.url));++// ---------------------------------------------------------------------------+// Helpers+// ---------------------------------------------------------------------------++function asString(value: unknown): string | null {+ return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;+}++function resolveHermesHome(config: Record<string, unknown>): string {+ const env =+ typeof config.env === "object" && config.env !== null && !Array.isArray(config.env)+ ? (config.env as Record<string, unknown>)+ : {};+ const configuredHome = asString(env.HOME);+ return configuredHome ? path.resolve(configuredHome) : os.homedir();+}++interface SkillFrontmatter {+ name?: string;+ description?: string;+ version?: string;+ category?: string;+ metadata?: Record<string, unknown>;+}++function parseSkillFrontmatter(content: string): SkillFrontmatter {+ const match = content.match(/^---\s*\n([\s\S]*?)\n---/);+ if (!match) return {};+ const frontmatter: Record<string, unknown> = {};+ for (const line of match[1].split("\n")) {+ const idx = line.indexOf(":");+ if (idx === -1) continue;+ const key = line.slice(0, idx).trim();+ let val: unknown = line.slice(idx + 1).trim();+ // Strip quotes+ if (typeof val === "string" && ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))) {+ val = val.slice(1, -1);+ }+ frontmatter[key] = val;+ }+ return frontmatter as SkillFrontmatter;+}++async function scanHermesSkills(+ skillsHome: string,+): Promise<AdapterSkillEntry[]> {+ const entries: AdapterSkillEntry[] = [];++ try {+ const categories = await fs.readdir(skillsHome, { withFileTypes: true });+ for (const cat of categories) {+ if (!cat.isDirectory()) continue;+ const catPath = path.join(skillsHome, cat.name);++ // Check if the category directory itself has a SKILL.md (top-level skill)+ const topLevelSkillMd = path.join(catPath, "SKILL.md");+ if (await fs.stat(topLevelSkillMd).catch(() => null)) {+ entries.push(await buildSkillEntry(cat.name, topLevelSkillMd, cat.name));+ }++ // Scan for sub-skills+ const items = await fs.readdir(catPath, { withFileTypes: true }).catch(() => []);+ for (const item of items) {+ if (!item.isDirectory()) continue;+ const skillMd = path.join(catPath, item.name, "SKILL.md");+ if (await fs.stat(skillMd).catch(() => null)) {+ const key = item.name;+ entries.push(await buildSkillEntry(key, skillMd, `${cat.name}/${item.name}`));+ }+ }+ }+ } catch {+ // ~/.hermes/skills/ doesn't exist — no skills available+ }++ return entries.sort((a, b) => a.key.localeCompare(b.key));+}++async function buildSkillEntry(+ key: string,+ skillMdPath: string,+ categoryPath: string,+): Promise<AdapterSkillEntry> {+ let description: string | null = null;+ try {+ const content = await fs.readFile(skillMdPath, "utf8");+ const fm = parseSkillFrontmatter(content);+ description = fm.description ?? null;+ } catch {+ // ignore+ }++ return {+ key,+ runtimeName: key,+ desired: true, // Hermes loads all available skills+ managed: false,+ state: "installed",+ origin: "user_installed",+ originLabel: "Hermes skill",+ locationLabel: `~/.hermes/skills/${categoryPath}`,+ readOnly: true, // Hermes manages its own skills — Paperclip can't toggle them+ sourcePath: skillMdPath,+ targetPath: null,+ detail: description,+ };+}++// ---------------------------------------------------------------------------+// Public API+// ---------------------------------------------------------------------------++async function buildHermesSkillSnapshot(config: Record<string, unknown>): Promise<AdapterSkillSnapshot> {+ const home = resolveHermesHome(config);+ const hermesSkillsHome = path.join(home, ".hermes", "skills");++ // 1. Scan Paperclip-managed skills (bundled with the adapter)+ const paperclipEntries = await readPaperclipRuntimeSkillEntries(config, __moduleDir);+ const desiredSkills = resolvePaperclipDesiredSkillNames(config, paperclipEntries);+ const desiredSet = new Set(desiredSkills);+ const availableByKey = new Map(paperclipEntries.map((e) => [e.key, e]));++ // 2. Scan Hermes's own skills from ~/.hermes/skills/+ const hermesSkillEntries = await scanHermesSkills(hermesSkillsHome);+ const hermesKeys = new Set(hermesSkillEntries.map((e) => e.key));++ // 3. Merge: Paperclip skills first (ephemeral), then Hermes skills+ const entries: AdapterSkillEntry[] = [];+ const warnings: string[] = [];++ // Paperclip-managed skills+ for (const entry of paperclipEntries) {+ const desired = desiredSet.has(entry.key);+ entries.push({+ key: entry.key,+ runtimeName: entry.runtimeName,+ desired,+ managed: true,+ state: desired ? "configured" : "available",+ origin: "company_managed",+ originLabel: "Managed by Paperclip",+ readOnly: false,+ sourcePath: entry.source,+ targetPath: null,+ detail: desired+ ? "Will be available on the next run via Hermes skill loading."+ : null,+ });+ }++ // Hermes-installed skills (read-only, always loaded)+ for (const entry of hermesSkillEntries) {+ // Skip if Paperclip already manages a skill with the same key+ if (availableByKey.has(entry.key)) continue;+ entries.push(entry);+ }++ // Check for desired skills that don't exist+ for (const desiredSkill of desiredSkills) {+ if (availableByKey.has(desiredSkill) || hermesKeys.has(desiredSkill)) continue;+ warnings.push(+ `Desired skill "${desiredSkill}" is not available in Paperclip or Hermes skills.`,+ );+ entries.push({+ key: desiredSkill,+ runtimeName: null,+ desired: true,+ managed: true,+ state: "missing",+ origin: "external_unknown",+ originLabel: "External or unavailable",+ readOnly: false,+ sourcePath: null,+ targetPath: null,+ detail:+ "Cannot find this skill in Paperclip or ~/.hermes/skills/.",+ });+ }++ return {+ adapterType: "hermes_local",+ supported: true,+ mode: "persistent",+ desiredSkills,+ entries,+ warnings,+ };+}++export async function listHermesSkills(+ ctx: AdapterSkillContext,+): Promise<AdapterSkillSnapshot> {+ return buildHermesSkillSnapshot(ctx.config);+}++export async function syncHermesSkills(+ ctx: AdapterSkillContext,+ _desiredSkills: string[],+): Promise<AdapterSkillSnapshot> {+ // Hermes manages its own skill loading — sync is a no-op.+ // Return the current snapshot so the UI stays in sync.+ return buildHermesSkillSnapshot(ctx.config);+}++export function resolveHermesDesiredSkillNames(+ config: Record<string, unknown>,+ availableEntries: Array<{ key: string; runtimeName?: string | null }>,+): string[] {+ return resolvePaperclipDesiredSkillNames(config, availableEntries);+}diff --git a/packages/adapters/hermes/src/server/test.ts b/packages/adapters/hermes/src/server/test.tsnew file mode 100644index 0000000000..b75ce020ca--- /dev/null+++ b/packages/adapters/hermes/src/server/test.ts@@ -0,0 +1,387 @@+/**+ * Environment test for the Hermes Agent adapter.+ *+ * Verifies that Hermes Agent is installed, accessible, and configured+ * before allowing the adapter to be used.+ */++import type {+ AdapterEnvironmentTestContext,+ AdapterEnvironmentTestResult,+ AdapterEnvironmentCheck,+} from "@paperclipai/adapter-utils";++import { execFile } from "node:child_process";+import { readFileSync } from "node:fs";+import { promisify } from "node:util";++import { HERMES_CLI, DEFAULT_MODEL, ADAPTER_TYPE, VALID_PROVIDERS } from "../shared/constants.js";+import { detectModel, resolveProvider, inferProviderFromModel } from "./detect-model.js";+import { resolveHermesCommand } from "./execute.js";++const execFileAsync = promisify(execFile);++function asString(v: unknown): string | undefined {+ return typeof v === "string" ? v : undefined;+}++// ---------------------------------------------------------------------------+// Checks+// ---------------------------------------------------------------------------++async function checkCliInstalled(+ command: string,+): Promise<AdapterEnvironmentCheck | null> {+ try {+ // Try to run the command to see if it exists+ await execFileAsync(command, ["--version"], { timeout: 10_000 });+ return null; // OK — it ran successfully+ } catch (err: unknown) {+ const e = err as NodeJS.ErrnoException;+ if (e.code === "ENOENT") {+ return {+ level: "error",+ message: `Hermes CLI "${command}" not found in PATH`,+ hint: "Install Hermes Agent: pip install hermes-agent",+ code: "hermes_cli_not_found",+ };+ }+ // Command exists but --version might have failed for some reason+ // Still consider it installed+ return null;+ }+}++async function checkCliVersion(+ command: string,+): Promise<AdapterEnvironmentCheck | null> {+ try {+ const { stdout } = await execFileAsync(command, ["--version"], {+ timeout: 10_000,+ });+ const version = stdout.trim();+ if (version) {+ return {+ level: "info",+ message: `Hermes Agent version: ${version}`,+ code: "hermes_version",+ };+ }+ return {+ level: "warn",+ message: "Could not determine Hermes Agent version",+ code: "hermes_version_unknown",+ };+ } catch {+ return {+ level: "warn",+ message:+ "Could not determine Hermes Agent version (hermes --version failed)",+ hint: "Make sure the hermes CLI is properly installed and functional",+ code: "hermes_version_failed",+ };+ }+}++async function checkPython(): Promise<AdapterEnvironmentCheck | null> {+ try {+ const { stdout } = await execFileAsync("python3", ["--version"], {+ timeout: 5_000,+ });+ const version = stdout.trim();+ const match = version.match(/(\d+)\.(\d+)/);+ if (match) {+ const major = parseInt(match[1], 10);+ const minor = parseInt(match[2], 10);+ if (major < 3 || (major === 3 && minor < 10)) {+ return {+ level: "error",+ message: `Python ${version} found — Hermes requires Python 3.10+`,+ hint: "Upgrade Python to 3.10 or later",+ code: "hermes_python_old",+ };+ }+ }+ return null; // OK+ } catch {+ return {+ level: "warn",+ message: "python3 not found in PATH",+ hint: "Hermes Agent requires Python 3.10+. Install it from python.org",+ code: "hermes_python_missing",+ };+ }+}++function checkModel(+ config: Record<string, unknown>,+): AdapterEnvironmentCheck | null {+ const model = asString(config.model);+ if (!model) {+ return {+ level: "info",+ message: "No model specified — Hermes will use its configured default model",+ hint: "Set a model explicitly in Paperclip only if you want to override your local Hermes configuration.",+ code: "hermes_configured_default_model",+ };+ }+ return {+ level: "info",+ message: `Model: ${model}`,+ code: "hermes_model_configured",+ };+}++async function checkApiKeys(+ config: Record<string, unknown>,+ detectedConfig: Awaited<ReturnType<typeof detectModel>> | null,+): Promise<AdapterEnvironmentCheck | null> {+ // The server resolves secret refs into config.env before calling testEnvironment,+ // so we check config.env first (adapter-configured secrets), then fall back to+ // process.env (server/host environment), then ~/.hermes/.env (Hermes local config).+ const envConfig = (config.env ?? {}) as Record<string, unknown>;+ const resolvedEnv: Record<string, string> = {};+ for (const [key, value] of Object.entries(envConfig)) {+ if (typeof value === "string" && value.length > 0) resolvedEnv[key] = value;+ }++ // Also read ~/.hermes/.env — Hermes stores API keys there by default and does+ // not export them to the parent process, so Paperclip's process.env won't+ // contain them. Parsing this file ensures the environment test reports+ // accurate results for keys that Hermes already knows about.+ const hermesEnvKeys: Record<string, string> = {};+ try {+ const homeDir = process.env.HOME || process.env.USERPROFILE || "/root";+ const hermesEnvPath = `${homeDir}/.hermes/.env`;+ const content = readFileSync(hermesEnvPath, "utf-8");+ for (const line of content.split("\n")) {+ const trimmed = line.trim();+ if (!trimmed || trimmed.startsWith("#")) continue;+ const eqIdx = trimmed.indexOf("=");+ if (eqIdx > 0) {+ const key = trimmed.substring(0, eqIdx).trim();+ const value = trimmed.substring(eqIdx + 1).trim();+ if (value.length > 0) hermesEnvKeys[key] = value;+ }+ }+ } catch {+ // ~/.hermes/.env may not exist — that's fine+ }++ const has = (key: string): boolean =>+ !!(resolvedEnv[key] ?? process.env[key] ?? hermesEnvKeys[key]);++ const hasAnthropic = has("ANTHROPIC_API_KEY");+ const hasOpenRouter = has("OPENROUTER_API_KEY");+ const hasOpenAI = has("OPENAI_API_KEY");+ const hasZai = has("ZAI_API_KEY");+ const hasKimi = has("KIMI_API_KEY");+ const hasMiniMax = has("MINIMAX_API_KEY");++ const providers: string[] = [];+ if (hasAnthropic) providers.push("Anthropic");+ if (hasOpenRouter) providers.push("OpenRouter");+ if (hasOpenAI) providers.push("OpenAI");+ if (hasZai) providers.push("Z.AI");+ if (hasKimi) providers.push("Kimi");+ if (hasMiniMax) providers.push("MiniMax");++ if (providers.length > 0) {+ return {+ level: "info",+ message: `API keys found: ${providers.join(", ")}`,+ code: "hermes_api_keys_found",+ };+ }++ const requestedModel = asString(config.model);++ const supportedProviders = VALID_PROVIDERS as readonly string[];+ const modelMatchesRequested =+ !!detectedConfig?.model &&+ (!requestedModel || detectedConfig.model.toLowerCase() === requestedModel.toLowerCase());++ const matchingHermesConfigApiKey =+ !!detectedConfig?.hasApiKey &&+ modelMatchesRequested;++ if (matchingHermesConfigApiKey && detectedConfig) {+ const providerLabel = detectedConfig.provider.trim();++ if (!providerLabel) {+ return {+ level: "info",+ message: "Hermes config includes an API key for the requested model via ~/.hermes/config.yaml without an explicit provider",+ hint: "Skipping the built-in API-key warning because Hermes can use model.api_key from the local Hermes config.",+ code: "hermes_api_key_in_config",+ };+ }++ if (!supportedProviders.includes(providerLabel)) {+ return {+ level: "info",+ message: `Hermes config includes runtime settings for unsupported adapter provider "${providerLabel}" via ~/.hermes/config.yaml`,+ hint: "Skipping the built-in API-key warning because Hermes can resolve this provider at runtime.",+ code: "hermes_custom_provider_config",+ };+ }++ return {+ level: "info",+ message: `Hermes config includes an API key for provider "${providerLabel}" via ~/.hermes/config.yaml`,+ hint: "Skipping the built-in API-key warning because Hermes can use model.api_key from the local Hermes config.",+ code: "hermes_api_key_in_config",+ };+ }++ return {+ level: "warn",+ message: "No LLM API keys found in environment",+ hint: "Set API keys in the agent's env secrets or ~/.hermes/.env. Hermes supports: ANTHROPIC_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY, ZAI_API_KEY, KIMI_API_KEY, MINIMAX_API_KEY",+ code: "hermes_no_api_keys",+ };+}++/**+ * Check provider/model consistency.+ * Warns if the configured provider might be wrong for the model.+ */+async function checkProviderConsistency(+ config: Record<string, unknown>,+ detectedConfig: Awaited<ReturnType<typeof detectModel>> | null,+): Promise<AdapterEnvironmentCheck | null> {+ const model = asString(config.model);+ if (!model) return null;++ const explicitProvider = asString(config.provider);++ const { provider: resolved, resolvedFrom } = resolveProvider({+ explicitProvider,+ detectedProvider: detectedConfig?.provider,+ detectedModel: detectedConfig?.model,+ detectedBaseUrl: detectedConfig?.baseUrl,+ detectedHasApiKey: detectedConfig?.hasApiKey,+ detectedApiMode: detectedConfig?.apiMode,+ model,+ });++ // If provider was explicitly set but doesn't match what Hermes config says,+ // that's worth flagging.+ if (explicitProvider && detectedConfig?.provider && explicitProvider !== detectedConfig.provider) {+ return {+ level: "warn",+ message: `Provider mismatch: adapterConfig has "${explicitProvider}" but ~/.hermes/config.yaml has "${detectedConfig.provider}". Using adapterConfig value.`,+ hint: `Model "${model}" may not work correctly with provider "${explicitProvider}". Consider aligning with your Hermes config or removing the explicit provider to use auto-detection.`,+ code: "hermes_provider_mismatch",+ };+ }++ // If Hermes config matches the requested model but uses an adapter-unsupported+ // provider such as "custom", do not report a false provider inference.+ if (!explicitProvider && resolvedFrom.startsWith("hermesConfigUnsupported:")) {+ const unsupportedProvider = resolvedFrom.split(":", 2)[1] || detectedConfig?.provider || "unknown";+ return {+ level: "info",+ message: `Hermes config uses unsupported adapter provider "${unsupportedProvider}" for model "${model}" — deferring to Hermes auto-detection`,+ hint: "Paperclip will avoid model-name provider inference here and let Hermes resolve the provider from ~/.hermes/config.yaml at runtime.",+ code: "hermes_provider_unsupported",+ };+ }++ // If matching Hermes config provides runtime signals without an explicit provider,+ // also defer to Hermes rather than inventing a provider from the model name.+ if (!explicitProvider && resolvedFrom === "hermesConfigRuntime") {+ return {+ level: "info",+ message: `Hermes config provides runtime settings for model "${model}" without an explicit adapter provider — deferring to Hermes auto-detection`,+ hint: "Paperclip will avoid model-name provider inference here and let Hermes resolve the provider from ~/.hermes/config.yaml at runtime.",+ code: "hermes_provider_runtime_config",+ };+ }++ // If provider was auto-detected (not explicitly set), log what was resolved+ if (!explicitProvider && resolvedFrom !== "auto") {+ return {+ level: "info",+ message: `Provider auto-detected as "${resolved}" (from ${resolvedFrom}) for model "${model}"`,+ code: "hermes_provider_detected",+ };+ }++ // If we couldn't resolve any provider, warn+ if (resolvedFrom === "auto" && !explicitProvider) {+ return {+ level: "warn",+ message: `Could not determine provider for model "${model}" — will use Hermes auto-detection`,+ hint: "Set an explicit provider in the agent config or ensure ~/.hermes/config.yaml has a matching provider for this model.",+ code: "hermes_provider_unknown",+ };+ }++ return null;+}++// ---------------------------------------------------------------------------+// Main test+// ---------------------------------------------------------------------------++export async function testEnvironment(+ ctx: AdapterEnvironmentTestContext,+): Promise<AdapterEnvironmentTestResult> {+ const config = (ctx.config ?? {}) as Record<string, unknown>;+ const command = resolveHermesCommand(config);+ const checks: AdapterEnvironmentCheck[] = [];++ // 1. CLI installed?+ const cliCheck = await checkCliInstalled(command);+ if (cliCheck) {+ checks.push(cliCheck);+ if (cliCheck.level === "error") {+ return {+ adapterType: ADAPTER_TYPE,+ status: "fail",+ checks,+ testedAt: new Date().toISOString(),+ };+ }+ }++ // 2. CLI version+ const versionCheck = await checkCliVersion(command);+ if (versionCheck) checks.push(versionCheck);++ // 3. Python available?+ const pythonCheck = await checkPython();+ if (pythonCheck) checks.push(pythonCheck);++ // 4. Model config+ const modelCheck = checkModel(config);+ if (modelCheck) checks.push(modelCheck);++ // 5. Detect Hermes config once for the remaining checks.+ let detectedConfig: Awaited<ReturnType<typeof detectModel>> | null = null;+ try {+ detectedConfig = await detectModel();+ } catch {+ // Non-fatal+ }++ // 6. API keys (check config.env — server resolves secrets before calling us)+ const apiKeyCheck = await checkApiKeys(config, detectedConfig);+ if (apiKeyCheck) checks.push(apiKeyCheck);++ // 7. Provider/model consistency+ const providerCheck = await checkProviderConsistency(config, detectedConfig);+ if (providerCheck) checks.push(providerCheck);++ // Determine overall status+ const hasErrors = checks.some((c) => c.level === "error");+ const hasWarnings = checks.some((c) => c.level === "warn");++ return {+ adapterType: ADAPTER_TYPE,+ status: hasErrors ? "fail" : hasWarnings ? "warn" : "pass",+ checks,+ testedAt: new Date().toISOString(),+ };+}diff --git a/packages/adapters/hermes/src/shared/constants.ts b/packages/adapters/hermes/src/shared/constants.tsnew file mode 100644index 0000000000..25f57cd86e--- /dev/null+++ b/packages/adapters/hermes/src/shared/constants.ts@@ -0,0 +1,104 @@+/**+ * Shared constants for the Hermes Agent adapter.+ */++/** Adapter type identifier registered with Paperclip. */+export const ADAPTER_TYPE = "hermes_local";++/** Human-readable label shown in the Paperclip UI. */+export const ADAPTER_LABEL = "Hermes Agent";++/** Default CLI binary name. */+export const HERMES_CLI = "hermes";++/** Default timeout for a single execution run (seconds). */+export const DEFAULT_TIMEOUT_SEC = 1800;++/** Grace period after SIGTERM before SIGKILL (seconds). */+export const DEFAULT_GRACE_SEC = 10;++/**+ * Default model to use if none specified.+ *+ * Use "auto" so that Hermes resolves the model from the user's local+ * ~/.hermes/config.yaml — preventing the adapter from overriding a+ * user's configured default (e.g. MiniMax, OpenRouter, etc.) with a+ * hardcoded Anthropic model during Paperclip onboarding.+ */+export const DEFAULT_MODEL = "auto";++/**+ * Valid --provider choices for the hermes CLI.+ * Must stay in sync with `hermes chat --help`.+ */+export const VALID_PROVIDERS = [+ "auto",+ "openrouter",+ "nous",+ "openai-codex",+ "copilot",+ "copilot-acp",+ "anthropic",+ "huggingface",+ "zai",+ "kimi-coding",+ "minimax",+ "minimax-cn",+ "kilocode",+] as const;++/**+ * Model-name prefix → provider hint mapping.+ * Used when no explicit provider is configured and we need to infer+ * the correct provider from the model string alone.+ *+ * Keys are lowercased prefix patterns; values must be valid provider names.+ * Longer prefixes are matched first (order matters).+ */+export const MODEL_PREFIX_PROVIDER_HINTS: [string, string][] = [+ // OpenAI-native models+ ["gpt-4", "openai-codex"],+ ["gpt-5", "copilot"],+ ["o1-", "openai-codex"],+ ["o3-", "openai-codex"],+ ["o4-", "openai-codex"],+ // Anthropic models+ ["claude", "anthropic"],+ // Google models (via openrouter or direct)+ ["gemini", "auto"],+ // Nous models+ ["hermes-", "nous"],+ // Z.AI / GLM models+ ["glm-", "zai"],+ // Kimi / Moonshot+ ["moonshot", "kimi-coding"],+ ["kimi", "kimi-coding"],+ // MiniMax+ ["minimax", "minimax"],+ // DeepSeek+ ["deepseek", "auto"],+ // Meta Llama+ ["llama", "auto"],+ // Qwen+ ["qwen", "auto"],+ // Mistral+ ["mistral", "auto"],+ // HuggingFace models (org/model format)+ ["huggingface/", "huggingface"],+];++/** Regex to extract session ID from Hermes CLI output. */+export const SESSION_ID_REGEX = /session[_ ](?:id|saved)[:\s]+([a-zA-Z0-9_-]+)/i;++/** Regex to extract token usage from Hermes output. */+export const TOKEN_USAGE_REGEX =+ /tokens?[:\s]+(\d+)\s*(?:input|in)\b.*?(\d+)\s*(?:output|out)\b/i;++/** Regex to extract cost from Hermes output. */+export const COST_REGEX = /(?:cost|spent)[:\s]*\$?([\d.]+)/i;++/** Prefix used by Hermes for tool output lines. */+export const TOOL_OUTPUT_PREFIX = "┊";++/** Prefix for Hermes thinking blocks. */+export const THINKING_PREFIX = "💭";diff --git a/packages/adapters/hermes/src/ui/build-config.ts b/packages/adapters/hermes/src/ui/build-config.tsnew file mode 100644index 0000000000..ef9c5fb67a--- /dev/null+++ b/packages/adapters/hermes/src/ui/build-config.ts@@ -0,0 +1,87 @@+/**+ * Build adapter configuration from UI form values.+ *+ * Translates Paperclip's CreateConfigValues into the adapterConfig+ * object stored in the agent record.+ *+ * NOTE: Provider resolution happens at runtime in execute.ts, not here.+ * The UI may or may not pass a provider field. If it does, we persist it+ * as the user's explicit override. If not, execute.ts will detect it from+ * ~/.hermes/config.yaml at runtime.+ */++import type { CreateConfigValues } from "@paperclipai/adapter-utils";++import {+ DEFAULT_TIMEOUT_SEC,+} from "../shared/constants.js";++/**+ * Build a Hermes Agent adapter config from the Paperclip UI form values.+ */+export function buildHermesConfig(+ v: CreateConfigValues,+): Record<string, unknown> {+ const ac: Record<string, unknown> = {};++ // Model+ if (v.model.trim()) {+ ac.model = v.model.trim();+ }++ // NOTE: Provider is NOT set here because the Paperclip UI form+ // (CreateConfigValues) does not expose a provider field.+ // Instead, provider is resolved at runtime in execute.ts using+ // a priority chain:+ // 1. adapterConfig.provider (if set via API directly)+ // 2. ~/.hermes/config.yaml detection+ // 3. Model-name prefix inference+ // 4. "auto" fallback+ // This ensures correct provider routing even for agents created+ // before provider tracking existed.++ // Execution limits — let the user configure these from the Paperclip UI.+ // timeoutSec: wall-clock kill timeout for the hermes child process.+ // maxTurnsPerRun: maps to Hermes's --max-turns (agent tool-calling iterations).+ ac.timeoutSec = DEFAULT_TIMEOUT_SEC;+ if (v.maxTurnsPerRun > 0) {+ ac.maxTurnsPerRun = v.maxTurnsPerRun;+ // Scale timeout to match: ~20s per tool turn is generous headroom.+ // Never go below the default (1800s / 30 min).+ ac.timeoutSec = Math.max(DEFAULT_TIMEOUT_SEC, v.maxTurnsPerRun * 20);+ }++ // Session persistence (default: on)+ ac.persistSession = true;++ // Working directory+ if (v.cwd) {+ ac.cwd = v.cwd;+ }++ // Custom hermes binary path+ if (v.command) {+ ac.hermesCommand = v.command;+ }++ // Extra CLI arguments+ if (v.extraArgs) {+ ac.extraArgs = v.extraArgs.split(/\s+/).filter(Boolean);+ }++ // Thinking/reasoning effort+ if (v.thinkingEffort) {+ const existing = (ac.extraArgs as string[]) || [];+ existing.push("--reasoning-effort", String(v.thinkingEffort));+ ac.extraArgs = existing;+ }++ // Prompt template+ if (v.promptTemplate) {+ ac.promptTemplate = v.promptTemplate;+ }++ // Heartbeat config is handled by Paperclip itself++ return ac;+}diff --git a/packages/adapters/hermes/src/ui/index.ts b/packages/adapters/hermes/src/ui/index.tsnew file mode 100644index 0000000000..3a49f11209--- /dev/null+++ b/packages/adapters/hermes/src/ui/index.ts@@ -0,0 +1,7 @@+/**+ * UI module exports — used by Paperclip's dashboard for run viewing+ * and agent configuration forms.+ */++export { parseHermesStdoutLine } from "./parse-stdout.js";+export { buildHermesConfig } from "./build-config.js";diff --git a/packages/adapters/hermes/src/ui/parse-stdout.ts b/packages/adapters/hermes/src/ui/parse-stdout.tsnew file mode 100644index 0000000000..6e48b40ed4--- /dev/null+++ b/packages/adapters/hermes/src/ui/parse-stdout.ts@@ -0,0 +1,283 @@+/**+ * Parse Hermes Agent stdout into TranscriptEntry objects for the Paperclip UI.+ *+ * Hermes CLI quiet-mode output patterns:+ * Assistant: " ┊ 💬 {text}"+ * Tool (TTY): " ┊ {emoji} {verb:9} {detail} {duration}"+ * Tool (pipe): " [done] ┊ {emoji} {verb:9} {detail} {duration} ({total})"+ * System: "[hermes] ..."+ *+ * We emit structured tool_call/tool_result pairs so Paperclip renders proper+ * tool cards (with status icons, expand/collapse) instead of raw stdout blocks.+ */++import type { TranscriptEntry } from "@paperclipai/adapter-utils";++import { TOOL_OUTPUT_PREFIX } from "../shared/constants.js";++// ── Kaomoji / noise stripping ──────────────────────────────────────────────++/**+ * Strip kawaii faces and decorative emoji from a tool summary line.+ * Leaves meaningful emoji (💻 for terminal, 🔍 for search, etc.) intact+ * by only stripping parenthesized kaomoji like (。◕‿◕。).+ */+function stripKaomoji(text: string): string {+ // Strip parenthesized kaomoji faces: (。◕‿◕。), (★ω★), etc.+ return text.replace(/[(][^()]{2,20}[)]\s*/gu, "").trim();+}++// ── Line classification ────────────────────────────────────────────────────++/** Check if a ┊ line is an assistant message (┊ 💬 ...). */+function isAssistantToolLine(stripped: string): boolean {+ return /^┊\s*💬/.test(stripped);+}++/** Extract assistant text from a ┊ 💬 line. */+function extractAssistantText(line: string): string {+ return line.replace(/^[\s┊]*💬\s*/, "").trim();+}++/**+ * Parse a tool completion line into structured data.+ *+ * Handles both TTY and pipe formats:+ * TTY: ┊ 💻 $ curl -s "..." 0.1s+ * Pipe: [done] ┊ 💻 $ curl -s "..." 0.1s (0.5s)+ */+function parseToolCompletionLine(+ line: string,+): { name: string; detail: string; duration: string; hasError: boolean } | null {+ // Strip leading whitespace and [done] prefix+ let cleaned = line.trim().replace(/^\[done\]\s*/, "");++ // Must start with ┊+ if (!cleaned.startsWith(TOOL_OUTPUT_PREFIX)) return null;++ // Remove ┊ prefix and any leading kaomoji face+ cleaned = cleaned.slice(TOOL_OUTPUT_PREFIX.length);+ cleaned = stripKaomoji(cleaned).trim();++ // Now format is: "{emoji} {verb:9} {detail} {duration}" or "{emoji} {verb:9} {detail} {duration} ({total})"+ // Example: "💻 $ curl -s ..." or "🔍 search pattern 0.1s"+ // The verb+detail are separated by whitespace, duration is at the end++ // Match: emoji + verb + detail + duration+ // Duration pattern: N.Ns (possibly followed by (N.Ns))+ const durationMatch = cleaned.match(/([\d.]+s)\s*(?:\([\d.]+s\))?\s*$/);+ const duration = durationMatch ? durationMatch[1] : "";++ // Remove duration from the end to get verb + detail+ let verbAndDetail = durationMatch+ ? cleaned.slice(0, cleaned.lastIndexOf(durationMatch[0])).trim()+ : cleaned;+ verbAndDetail = verbAndDetail.replace(/^\p{Emoji_Presentation}\s*/u, "");++ // Check for error suffixes+ const hasError = /\[(?:exit \d+|error|full)\]/.test(verbAndDetail) ||+ /\[error\]\s*$/.test(cleaned);++ // The first token (after emoji) is the verb, rest is detail+ // Verbs are always a single word or symbol ($ for terminal)+ const parts = verbAndDetail.match(/^(\S+)\s+(.*)/);+ if (!parts) {+ return { name: "tool", detail: verbAndDetail, duration, hasError };+ }++ const verb = parts[1];+ const detail = parts[2].trim();++ // Map Hermes verbs to readable tool names+ const nameMap: Record<string, string> = {+ "$": "shell",+ "exec": "shell",+ "terminal": "shell",+ "search": "search",+ "fetch": "fetch",+ "crawl": "crawl",+ "navigate": "browser",+ "snapshot": "browser",+ "click": "browser",+ "type": "browser",+ "scroll": "browser",+ "back": "browser",+ "press": "browser",+ "close": "browser",+ "images": "browser",+ "vision": "browser",+ "read": "read",+ "write": "write",+ "patch": "patch",+ "grep": "search",+ "find": "search",+ "plan": "plan",+ "recall": "recall",+ "proc": "process",+ "delegate": "delegate",+ "todo": "todo",+ "memory": "memory",+ "clarify": "clarify",+ "session_search": "recall",+ "code": "execute",+ "execute": "execute",+ "web_search": "search",+ "web_extract": "fetch",+ "browser_navigate": "browser",+ "browser_click": "browser",+ "browser_type": "browser",+ "browser_snapshot": "browser",+ "browser_vision": "browser",+ "browser_scroll": "browser",+ "browser_press": "browser",+ "browser_back": "browser",+ "browser_close": "browser",+ "browser_get_images": "browser",+ "read_file": "read",+ "write_file": "write_file",+ "search_files": "search",+ "patch_file": "patch",+ "execute_code": "execute",+ };++ const name = nameMap[verb.toLowerCase()] || verb;++ return { name, detail, duration, hasError };+}++// ── Synthetic tool ID generation ────────────────────────────────────────────++let toolCallCounter = 0;++/**+ * Generate a synthetic toolUseId for pairing tool_call with tool_result.+ * Paperclip uses this to match them in normalizeTranscript.+ */+function syntheticToolUseId(): string {+ return `hermes-tool-${++toolCallCounter}`;+}++// ── Thinking detection ─────────────────────────────────────────────────────++function isThinkingLine(line: string): boolean {+ return (+ line.includes("💭") ||+ line.startsWith("<thinking>") ||+ line.startsWith("</thinking>") ||+ line.startsWith("Thinking:")+ );+}++// ── Main parser ────────────────────────────────────────────────────────────++/**+ * Parse a single line of Hermes stdout into transcript entries.+ *+ * Emits structured tool_call/tool_result pairs (with synthetic IDs) so+ * Paperclip renders proper tool cards with status icons and expand/collapse.+ *+ * @param line Raw stdout line from Hermes CLI+ * @param ts ISO timestamp for the entry+ * @returns Array of TranscriptEntry objects (may be empty)+ */+export function parseHermesStdoutLine(+ line: string,+ ts: string,+): TranscriptEntry[] {+ const trimmed = line.trim();+ if (!trimmed) return [];++ // ── System/adapter messages ────────────────────────────────────────────+ if (trimmed.startsWith("[hermes]") || trimmed.startsWith("[paperclip]")) {+ return [{ kind: "system", ts, text: trimmed }];+ }++ // ── Non-quiet mode tool start lines: [tool] (kaomoji) emoji verb ... ──+ // These are redundant — the tool_call/tool_result pair arrives later from+ // the ┊ completion line. Skip them to avoid duplicate entries.+ if (trimmed.startsWith("[tool]")) {+ return [];+ }++ // ── MCP / server init noise reclassified from stderr by wrappedOnLog ──+ // Pattern: [2026-03-25T10:40:53.941Z] INFO: ...+ // Emit as stderr so Paperclip groups them into the amber accordion.+ if (/^\[\d{4}-\d{2}-\d{2}T/.test(trimmed)) {+ return [{ kind: "stderr", ts, text: trimmed }];+ }++ // ── Standalone spinner remnants: "💻 Completed", "💻\nCompleted", etc. ─+ // These are non-quiet mode spinner frame leftovers — skip them.+ if (/^\p{Emoji_Presentation}\s*(Completed|Running|Error)?\s*$/u.test(trimmed)) {+ return [];+ }++ // ── Session info line ────────────────────────────────────────────────+ if (trimmed.startsWith("session_id:")) {+ return [{ kind: "system", ts, text: trimmed }];+ }++ // ── Quiet-mode tool/message lines (prefixed with ┊) ────────────────────+ if (trimmed.includes(TOOL_OUTPUT_PREFIX)) {+ // Assistant message: ┊ 💬 {text}+ if (isAssistantToolLine(trimmed)) {+ return [{ kind: "assistant", ts, text: extractAssistantText(trimmed) }];+ }++ // Tool completion: ┊ {emoji} {verb} {detail} {duration}+ const toolInfo = parseToolCompletionLine(trimmed);+ if (toolInfo) {+ const id = syntheticToolUseId();+ const detailText = toolInfo.duration+ ? `${toolInfo.detail} ${toolInfo.duration}`+ : toolInfo.detail;++ return [+ {+ kind: "tool_call" as const,+ ts,+ name: toolInfo.name,+ input: { detail: toolInfo.detail },+ toolUseId: id,+ },+ {+ kind: "tool_result" as const,+ ts,+ toolUseId: id,+ content: detailText,+ isError: toolInfo.hasError,+ },+ ] as TranscriptEntry[];+ }++ // Fallback: raw ┊ line that doesn't match tool format+ const stripped = trimmed+ .replace(/^\[done\]\s*/, "")+ .replace(new RegExp(`^${TOOL_OUTPUT_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\s*`), "")+ .trim();+ return [{ kind: "stdout", ts, text: stripped }];+ }++ // ── Thinking blocks ────────────────────────────────────────────────────+ if (isThinkingLine(trimmed)) {+ return [+ {+ kind: "thinking",+ ts,+ text: trimmed.replace(/^💭\s*/, ""),+ },+ ];+ }++ // ── Error output ───────────────────────────────────────────────────────+ if (+ trimmed.startsWith("Error:") ||+ trimmed.startsWith("ERROR:") ||+ trimmed.startsWith("Traceback")+ ) {+ return [{ kind: "stderr", ts, text: trimmed }];+ }++ // ── Regular assistant output ───────────────────────────────────────────+ return [{ kind: "assistant", ts, text: trimmed }];+}diff --git a/packages/adapters/hermes/tsconfig.json b/packages/adapters/hermes/tsconfig.jsonnew file mode 100644index 0000000000..8fea361a34--- /dev/null+++ b/packages/adapters/hermes/tsconfig.json@@ -0,0 +1,9 @@+{+ "extends": "../../../tsconfig.base.json",+ "compilerOptions": {+ "outDir": "dist",+ "rootDir": "src",+ "types": ["node"]+ },+ "include": ["src"]+}diff --git a/packages/adapters/hermes/ui-parser.cjs b/packages/adapters/hermes/ui-parser.cjsnew file mode 100644index 0000000000..618c37606c--- /dev/null+++ b/packages/adapters/hermes/ui-parser.cjs@@ -0,0 +1,193 @@+"use strict";++const TOOL_OUTPUT_PREFIX = "\u250a";++function stripKaomoji(text) {+ return text.replace(/[(][^()]{2,20}[)]\s*/gu, "").trim();+}++function isAssistantToolLine(stripped) {+ return /^\u250a\s*\u{1f4ac}/u.test(stripped);+}++function extractAssistantText(line) {+ return line.replace(/^[\s\u250a]*\u{1f4ac}\s*/u, "").trim();+}++function parseToolCompletionLine(line) {+ let cleaned = line.trim().replace(/^\[done\]\s*/, "");+ if (!cleaned.startsWith(TOOL_OUTPUT_PREFIX)) return null;++ cleaned = cleaned.slice(TOOL_OUTPUT_PREFIX.length);+ cleaned = stripKaomoji(cleaned).trim();++ const durationMatch = cleaned.match(/([\d.]+s)\s*(?:\([\d.]+s\))?\s*$/);+ const duration = durationMatch ? durationMatch[1] : "";+ const verbAndDetail = durationMatch+ ? cleaned.slice(0, cleaned.lastIndexOf(durationMatch[0])).trim()+ : cleaned;+ const detailWithoutEmoji = verbAndDetail.replace(/^\p{Emoji_Presentation}\s*/u, "");++ const hasError = /\[(?:exit \d+|error|full)\]/.test(detailWithoutEmoji) ||+ /\[error\]\s*$/.test(cleaned);++ const parts = detailWithoutEmoji.match(/^(\S+)\s+(.*)/);+ if (!parts) {+ return { name: "tool", detail: detailWithoutEmoji, duration, hasError };+ }++ const verb = parts[1];+ const detail = parts[2].trim();+ const nameMap = {+ "$": "shell",+ exec: "shell",+ terminal: "shell",+ search: "search",+ fetch: "fetch",+ crawl: "crawl",+ navigate: "browser",+ snapshot: "browser",+ click: "browser",+ type: "browser",+ scroll: "browser",+ back: "browser",+ press: "browser",+ close: "browser",+ images: "browser",+ vision: "browser",+ read: "read",+ write: "write",+ patch: "patch",+ grep: "search",+ find: "search",+ plan: "plan",+ recall: "recall",+ proc: "process",+ delegate: "delegate",+ todo: "todo",+ memory: "memory",+ clarify: "clarify",+ session_search: "recall",+ code: "execute",+ execute: "execute",+ web_search: "search",+ web_extract: "fetch",+ browser_navigate: "browser",+ browser_click: "browser",+ browser_type: "browser",+ browser_snapshot: "browser",+ browser_vision: "browser",+ browser_scroll: "browser",+ browser_press: "browser",+ browser_back: "browser",+ browser_close: "browser",+ browser_get_images: "browser",+ read_file: "read",+ write_file: "write_file",+ search_files: "search",+ patch_file: "patch",+ execute_code: "execute",+ };++ return {+ name: nameMap[verb.toLowerCase()] || verb,+ detail,+ duration,+ hasError,+ };+}++let toolCallCounter = 0;++function syntheticToolUseId() {+ toolCallCounter += 1;+ return `hermes-tool-${toolCallCounter}`;+}++function isThinkingLine(line) {+ return (+ line.includes("\u{1f4ad}") ||+ line.startsWith("<thinking>") ||+ line.startsWith("</thinking>") ||+ line.startsWith("Thinking:")+ );+}++function parseStdoutLine(line, ts) {+ const trimmed = line.trim();+ if (!trimmed) return [];++ if (trimmed.startsWith("[hermes]") || trimmed.startsWith("[paperclip]")) {+ return [{ kind: "system", ts, text: trimmed }];+ }++ if (trimmed.startsWith("[tool]")) {+ return [];+ }++ if (/^\[\d{4}-\d{2}-\d{2}T/.test(trimmed)) {+ return [{ kind: "stderr", ts, text: trimmed }];+ }++ if (/^\p{Emoji_Presentation}\s*(Completed|Running|Error)?\s*$/u.test(trimmed)) {+ return [];+ }++ if (trimmed.startsWith("session_id:")) {+ return [{ kind: "system", ts, text: trimmed }];+ }++ if (trimmed.includes(TOOL_OUTPUT_PREFIX)) {+ if (isAssistantToolLine(trimmed)) {+ return [{ kind: "assistant", ts, text: extractAssistantText(trimmed) }];+ }++ const toolInfo = parseToolCompletionLine(trimmed);+ if (toolInfo) {+ const id = syntheticToolUseId();+ const detailText = toolInfo.duration+ ? `${toolInfo.detail} ${toolInfo.duration}`+ : toolInfo.detail;++ return [+ {+ kind: "tool_call",+ ts,+ name: toolInfo.name,+ input: { detail: toolInfo.detail },+ toolUseId: id,+ },+ {+ kind: "tool_result",+ ts,+ toolUseId: id,+ content: detailText,+ isError: toolInfo.hasError,+ },+ ];+ }++ const escapedPrefix = TOOL_OUTPUT_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");+ const stripped = trimmed+ .replace(/^\[done\]\s*/, "")+ .replace(new RegExp(`^${escapedPrefix}\\s*`), "")+ .trim();+ return [{ kind: "stdout", ts, text: stripped }];+ }++ if (isThinkingLine(trimmed)) {+ return [{ kind: "thinking", ts, text: trimmed.replace(/^\u{1f4ad}\s*/u, "") }];+ }++ if (+ trimmed.startsWith("Error:") ||+ trimmed.startsWith("ERROR:") ||+ trimmed.startsWith("Traceback")+ ) {+ return [{ kind: "stderr", ts, text: trimmed }];+ }++ return [{ kind: "assistant", ts, text: trimmed }];+}++module.exports = { parseStdoutLine };diff --git a/packages/adapters/hermes/vitest.config.ts b/packages/adapters/hermes/vitest.config.tsnew file mode 100644index 0000000000..ad7d95889a--- /dev/null+++ b/packages/adapters/hermes/vitest.config.ts@@ -0,0 +1,8 @@+import { defineConfig } from "vitest/config";++export default defineConfig({+ test: {+ environment: "node",+ exclude: ["dist/**", "node_modules/**"],+ },+});diff --git a/packages/adapters/opencode-local/src/server/execute.remote.test.ts b/packages/adapters/opencode-local/src/server/execute.remote.test.tsindex f13fa4d5e6..dab6280423 100644--- a/packages/adapters/opencode-local/src/server/execute.remote.test.ts+++ b/packages/adapters/opencode-local/src/server/execute.remote.test.ts@@ -1,7 +1,7 @@import { mkdir, mkdtemp, rm } from "node:fs/promises";import os from "node:os";import path from "node:path";-import { afterEach, describe, expect, it, vi } from "vitest";+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";const {runChildProcess,@@ -102,9 +102,19 @@ import { execute } from "./execute.js";describe("opencode remote execution", () => {const cleanupDirs: string[] = [];+ const originalOpenCodeAllowAllModels = process.env.OPENCODE_ALLOW_ALL_MODELS;++ beforeEach(() => {+ delete process.env.OPENCODE_ALLOW_ALL_MODELS;+ });afterEach(async () => {vi.clearAllMocks();+ if (originalOpenCodeAllowAllModels === undefined) {+ delete process.env.OPENCODE_ALLOW_ALL_MODELS;+ } else {+ process.env.OPENCODE_ALLOW_ALL_MODELS = originalOpenCodeAllowAllModels;+ }while (cleanupDirs.length > 0) {const dir = cleanupDirs.pop();if (!dir) continue;diff --git a/packages/db/src/migrations/0124_agent_api_key_scope_config.sql b/packages/db/src/migrations/0124_agent_api_key_scope_config.sqlnew file mode 100644index 0000000000..52167d2526--- /dev/null+++ b/packages/db/src/migrations/0124_agent_api_key_scope_config.sql@@ -0,0 +1 @@+ALTER TABLE "agent_api_keys" ADD COLUMN IF NOT EXISTS "scope_config" jsonb;diff --git a/packages/db/src/migrations/meta/_journal.json b/packages/db/src/migrations/meta/_journal.jsonindex 1956b93218..6c63f8b5d9 100644--- a/packages/db/src/migrations/meta/_journal.json+++ b/packages/db/src/migrations/meta/_journal.json@@ -869,6 +869,13 @@"when": 1781903700000,"tag": "0123_document_annotation_source_trust","breakpoints": true+ },+ {+ "idx": 124,+ "version": "7",+ "when": 1782440000000,+ "tag": "0124_agent_api_key_scope_config",+ "breakpoints": true}]}diff --git a/packages/db/src/schema/agent_api_keys.ts b/packages/db/src/schema/agent_api_keys.tsindex 025fab437f..8cc430ae00 100644--- a/packages/db/src/schema/agent_api_keys.ts+++ b/packages/db/src/schema/agent_api_keys.ts@@ -1,4 +1,5 @@-import { pgTable, uuid, text, timestamp, index } from "drizzle-orm/pg-core";+import { pgTable, uuid, text, timestamp, index, jsonb } from "drizzle-orm/pg-core";+import type { AgentApiKeyScope } from "@paperclipai/shared";import { agents } from "./agents.js";import { companies } from "./companies.js";@@ -10,6 +11,7 @@ export const agentApiKeys = pgTable(companyId: uuid("company_id").notNull().references(() => companies.id),name: text("name").notNull(),keyHash: text("key_hash").notNull(),+ scopeConfig: jsonb("scope_config").$type<AgentApiKeyScope | null>(),lastUsedAt: timestamp("last_used_at", { withTimezone: true }),revokedAt: timestamp("revoked_at", { withTimezone: true }),createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),diff --git a/packages/shared/src/constants.ts b/packages/shared/src/constants.tsindex f4c9836762..8725947eca 100644--- a/packages/shared/src/constants.ts+++ b/packages/shared/src/constants.ts@@ -35,6 +35,8 @@ export const AGENT_ADAPTER_TYPES = ["codex_local","cursor_cloud","gemini_local",+ "hermes_gateway",+ "hermes_local","opencode_local","pi_local","cursor",diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.tsindex d098b39d00..07f4dd4256 100644--- a/packages/shared/src/index.ts+++ b/packages/shared/src/index.ts@@ -1052,6 +1052,10 @@ export {updateAgentInstructionsBundleSchema,upsertAgentInstructionsFileSchema,updateAgentInstructionsPathSchema,+ agentApiKeyScopeSchema,+ normalizeAgentApiKeyScope,+ standardAgentKeyScopeSchema,+ taskBridgeAgentKeyScopeSchema,createAgentKeySchema,agentMineInboxQuerySchema,wakeAgentSchema,@@ -1065,6 +1069,8 @@ export {type UpdateAgentInstructionsBundle,type UpsertAgentInstructionsFile,type UpdateAgentInstructionsPath,+ type AgentApiKeyScope,+ type TaskBridgeAgentKeyScope,type CreateAgentKey,type AgentMineInboxQuery,type WakeAgent,diff --git a/packages/shared/src/types/agent.ts b/packages/shared/src/types/agent.tsindex ad16c7dad8..38df57ba1e 100644--- a/packages/shared/src/types/agent.ts+++ b/packages/shared/src/types/agent.ts@@ -14,6 +14,7 @@ import type {TrustPreset,} from "../trust-policy.js";import type { AgentOrgChainHealth } from "../agent-eligibility.js";+import type { AgentApiKeyScope } from "../validators/agent.js";export interface AgentPermissions extends Record<string, unknown> {canCreateAgents: boolean;@@ -116,6 +117,7 @@ export type ClearAgentErrorResponse = Agent;export interface AgentKeyCreated {id: string;name: string;+ scope: AgentApiKeyScope;token: string;createdAt: Date;}diff --git a/packages/shared/src/validators/agent.ts b/packages/shared/src/validators/agent.tsindex 69f1b5b233..65934b7e6d 100644--- a/packages/shared/src/validators/agent.ts+++ b/packages/shared/src/validators/agent.ts@@ -114,8 +114,45 @@ export const updateAgentInstructionsPathSchema = z.object({export type UpdateAgentInstructionsPath = z.infer<typeof updateAgentInstructionsPathSchema>;+export const taskBridgeAgentKeyScopeSchema = z.object({+ kind: z.literal("task_bridge"),+ projectId: z.string().uuid().optional().nullable(),+ projectIds: z.array(z.string().uuid()).max(50).optional(),+ parentIssueId: z.string().uuid().optional().nullable(),+ parentIssueIds: z.array(z.string().uuid()).max(50).optional(),+ allowedAssigneeAgentIds: z.array(z.string().uuid()).max(50).optional(),+}).strict().superRefine((value, ctx) => {+ const hasProjectBoundary = Boolean(value.projectId) || Boolean(value.projectIds?.length);+ const hasParentBoundary = Boolean(value.parentIssueId) || Boolean(value.parentIssueIds?.length);+ if (!hasProjectBoundary && !hasParentBoundary) {+ ctx.addIssue({+ code: z.ZodIssueCode.custom,+ message: "task_bridge keys require at least one project or parent issue boundary",+ path: ["projectId"],+ });+ }+});++export const standardAgentKeyScopeSchema = z.object({+ kind: z.literal("standard"),+}).strict();++export const agentApiKeyScopeSchema = z.union([+ standardAgentKeyScopeSchema,+ taskBridgeAgentKeyScopeSchema,+]);++export type AgentApiKeyScope = z.infer<typeof agentApiKeyScopeSchema>;+export type TaskBridgeAgentKeyScope = z.infer<typeof taskBridgeAgentKeyScopeSchema>;++export function normalizeAgentApiKeyScope(value: unknown): AgentApiKeyScope {+ const parsed = agentApiKeyScopeSchema.safeParse(value);+ return parsed.success ? parsed.data : { kind: "standard" };+}+export const createAgentKeySchema = z.object({name: z.string().min(1).default("default"),+ scope: agentApiKeyScopeSchema.optional().default({ kind: "standard" }),});export type CreateAgentKey = z.infer<typeof createAgentKeySchema>;diff --git a/packages/shared/src/validators/index.ts b/packages/shared/src/validators/index.tsindex 43fcc8ac84..9e3fd62649 100644--- a/packages/shared/src/validators/index.ts+++ b/packages/shared/src/validators/index.ts@@ -207,6 +207,10 @@ export {updateAgentInstructionsBundleSchema,upsertAgentInstructionsFileSchema,updateAgentInstructionsPathSchema,+ agentApiKeyScopeSchema,+ normalizeAgentApiKeyScope,+ standardAgentKeyScopeSchema,+ taskBridgeAgentKeyScopeSchema,createAgentKeySchema,agentMineInboxQuerySchema,wakeAgentSchema,@@ -220,6 +224,8 @@ export {type UpdateAgentInstructionsBundle,type UpsertAgentInstructionsFile,type UpdateAgentInstructionsPath,+ type AgentApiKeyScope,+ type TaskBridgeAgentKeyScope,type CreateAgentKey,type AgentMineInboxQuery,type WakeAgent,diff --git a/scripts/bootstrap-npm-package.mjs b/scripts/bootstrap-npm-package.mjsindex 9b1e01beb0..b255d59ab6 100644--- a/scripts/bootstrap-npm-package.mjs+++ b/scripts/bootstrap-npm-package.mjs@@ -2,7 +2,7 @@import { spawnSync } from "node:child_process";import { fileURLToPath } from "node:url";-import { dirname, join, resolve } from "node:path";+import { dirname, resolve } from "node:path";import { buildReleasePackagePlan } from "./release-package-map.mjs";@@ -187,13 +187,24 @@ function printNextSteps(pkg) {);}-function publishPackage(pkg, otp) {- const publishArgs = ["publish", "--access", "public"];+function buildPublishArgs(pkg, { dryRun = false, otp = null } = {}) {+ const args = ["publish", pkg.dir, "--no-git-checks", "--access", "public"];++ if (dryRun) {+ args.push("--dry-run");+ }+if (otp) {- publishArgs.push("--otp", otp);+ args.push("--otp", otp);}- const result = runCommand("npm", publishArgs, { cwd: join(repoRoot, pkg.dir) });+ return args;+}++function publishPackage(pkg, otp) {+ const publishArgs = buildPublishArgs(pkg, { otp });++ const result = runCommand("pnpm", publishArgs);const stdout = result.stdout ?? "";const stderr = result.stderr ?? "";const output = `${stdout}\n${stderr}`.trim();@@ -214,7 +225,7 @@ function publishPackage(pkg, otp) {);}- throw new Error(`${formatCommand("npm", publishArgs)} failed with status ${result.status ?? "unknown"}`);+ throw new Error(`${formatCommand("pnpm", publishArgs)} failed with status ${result.status ?? "unknown"}`);}function main(argv) {@@ -255,7 +266,7 @@ function main(argv) {}process.stdout.write(`Previewing publish payload for ${pkg.name}...\n`);- runChecked("npm", ["pack", "--dry-run"], { cwd: join(repoRoot, pkg.dir) });+ runChecked("pnpm", buildPublishArgs(pkg, { dryRun: true }));if (!publish) {process.stdout.write(@@ -286,6 +297,7 @@ if (isDirectRun) {}export {+ buildPublishArgs,ensureNpmAuth,inspectNpmPackage,parseArgs,diff --git a/scripts/bootstrap-npm-package.test.mjs b/scripts/bootstrap-npm-package.test.mjsindex 32270f6be4..2f68662a90 100644--- a/scripts/bootstrap-npm-package.test.mjs+++ b/scripts/bootstrap-npm-package.test.mjs@@ -1,7 +1,7 @@import assert from "node:assert/strict";import test from "node:test";-import { parseArgs, resolveTargetPackage } from "./bootstrap-npm-package.mjs";+import { buildPublishArgs, parseArgs, resolveTargetPackage } from "./bootstrap-npm-package.mjs";test("parseArgs recognizes publish and skip-build flags", () => {assert.deepEqual(parseArgs(["@paperclipai/adapter-acpx-local", "--publish", "--skip-build"]), {@@ -58,3 +58,30 @@ test("resolveTargetPackage includes the workspace diff plugin bootstrap package"assert.equal(pkg.dir, "packages/plugins/plugin-workspace-diff");});++test("buildPublishArgs publishes from the repo root through pnpm", () => {+ const pkg = { dir: "packages/adapters/hermes", name: "@paperclipai/hermes-paperclip-adapter" };++ assert.deepEqual(buildPublishArgs(pkg), [+ "publish",+ "packages/adapters/hermes",+ "--no-git-checks",+ "--access",+ "public",+ ]);+});++test("buildPublishArgs includes dry-run and otp flags when requested", () => {+ const pkg = { dir: "packages/adapters/hermes", name: "@paperclipai/hermes-paperclip-adapter" };++ assert.deepEqual(buildPublishArgs(pkg, { dryRun: true, otp: "123456" }), [+ "publish",+ "packages/adapters/hermes",+ "--no-git-checks",+ "--access",+ "public",+ "--dry-run",+ "--otp",+ "123456",+ ]);+});diff --git a/scripts/generate-npm-package-json.mjs b/scripts/generate-npm-package-json.mjsindex f7be8cc04b..72fd63f443 100644--- a/scripts/generate-npm-package-json.mjs+++ b/scripts/generate-npm-package-json.mjs@@ -32,6 +32,8 @@ const workspacePaths = ["packages/adapter-utils","packages/adapters/claude-local","packages/adapters/codex-local",+ "packages/adapters/hermes-gateway",+ "packages/adapters/hermes","packages/adapters/opencode-local","packages/adapters/openclaw-gateway",];diff --git a/scripts/release-package-manifest.json b/scripts/release-package-manifest.jsonindex 9f85129782..d0c1e83579 100644--- a/scripts/release-package-manifest.json+++ b/scripts/release-package-manifest.json@@ -39,6 +39,16 @@"name": "@paperclipai/adapter-grok-local","publishFromCi": true},+ {+ "dir": "packages/adapters/hermes",+ "name": "@paperclipai/hermes-paperclip-adapter",+ "publishFromCi": true+ },+ {+ "dir": "packages/adapters/hermes-gateway",+ "name": "@paperclipai/adapter-hermes-gateway",+ "publishFromCi": false+ },{"dir": "packages/adapters/opencode-local","name": "@paperclipai/adapter-opencode-local",diff --git a/scripts/release-package-map.test.mjs b/scripts/release-package-map.test.mjsindex b632b92e8b..577186057b 100644--- a/scripts/release-package-map.test.mjs+++ b/scripts/release-package-map.test.mjs@@ -24,6 +24,17 @@ test("release package list only contains CI-enrolled packages", () => {assert.ok(enabledPackages.every((pkg) => pkg.publishFromCi === true));});+test("Hermes release surface publishes the unified built-in package and keeps gateway as a shim", () => {+ const packages = buildReleasePackagePlan();+ const hermes = packages.find((pkg) => pkg.name === "@paperclipai/hermes-paperclip-adapter");+ const gatewayShim = packages.find((pkg) => pkg.name === "@paperclipai/adapter-hermes-gateway");++ assert.equal(hermes?.dir, "packages/adapters/hermes");+ assert.equal(hermes?.publishFromCi, true);+ assert.equal(gatewayShim?.dir, "packages/adapters/hermes-gateway");+ assert.equal(gatewayShim?.publishFromCi, false);+});+test("release package configuration validates successfully", () => {assert.doesNotThrow(() => checkConfiguration());});diff --git a/scripts/smoke/hermes-gateway-e2e.sh b/scripts/smoke/hermes-gateway-e2e.shnew file mode 100755index 0000000000..7aac9c1736--- /dev/null+++ b/scripts/smoke/hermes-gateway-e2e.sh@@ -0,0 +1,1007 @@+#!/usr/bin/env bash+set -euo pipefail++log() {+ echo "[hermes-gateway-e2e] $*"+}++warn() {+ echo "[hermes-gateway-e2e] WARN: $*" >&2+}++fail() {+ echo "[hermes-gateway-e2e] ERROR: $*" >&2+ if [[ -n "${HERMES_SMOKE_DIAG_DIR:-}" ]]; then+ mkdir -p "$HERMES_SMOKE_DIAG_DIR" 2>/dev/null || true+ printf "%s\n" "$*" > "${HERMES_SMOKE_DIAG_DIR}/failure.txt" 2>/dev/null || true+ fi+ exit 1+}++require_cmd() {+ local cmd="$1"+ command -v "$cmd" >/dev/null 2>&1 || fail "missing required command: ${cmd}"+}++PAPERCLIP_API_URL="${PAPERCLIP_API_URL:-http://127.0.0.1:3100}"+API_BASE="${PAPERCLIP_API_URL%/}/api"+COMPANY_ID="${COMPANY_ID:-${PAPERCLIP_COMPANY_ID:-}}"+COMPANY_SELECTOR="${COMPANY_SELECTOR:-}"++RUN_SUFFIX="${HERMES_SMOKE_RUN_SUFFIX:-$(date +%Y%m%d-%H%M%S)-$$}"+HERMES_IMAGE="${HERMES_IMAGE:-paperclip-hermes-gateway-smoke:local}"+HERMES_VERSION="${HERMES_VERSION:-0.17.0}"+HERMES_BUILD="${HERMES_BUILD:-1}"+HERMES_DOCKER_CONTEXT="${HERMES_DOCKER_CONTEXT:-docker/hermes-gateway-smoke}"+HERMES_CONTAINER_NAME="${HERMES_CONTAINER_NAME:-paperclip-hermes-gateway-smoke-${RUN_SUFFIX}}"+HERMES_GATEWAY_PORT="${HERMES_GATEWAY_PORT:-8642}"+HERMES_GATEWAY_API_BASE_URL="${HERMES_GATEWAY_API_BASE_URL:-http://127.0.0.1:${HERMES_GATEWAY_PORT}}"+HERMES_GATEWAY_PROBE_URL="${HERMES_GATEWAY_PROBE_URL:-http://127.0.0.1:${HERMES_GATEWAY_PORT}}"+HERMES_GATEWAY_API_KEY="${HERMES_GATEWAY_API_KEY:-${API_SERVER_KEY:-}}"+HERMES_GATEWAY_ALLOW_INSECURE_HTTP="${HERMES_GATEWAY_ALLOW_INSECURE_HTTP:-0}"+HERMES_GATEWAY_SESSION_KEY_STRATEGY="${HERMES_GATEWAY_SESSION_KEY_STRATEGY:-issue}"+HERMES_ADAPTER_TIMEOUT_SEC="${HERMES_ADAPTER_TIMEOUT_SEC:-180}"+HERMES_DIRECT_RUN_TIMEOUT_SEC="${HERMES_DIRECT_RUN_TIMEOUT_SEC:-180}"+HERMES_DIRECT_RUN_EVENTS_TIMEOUT_SEC="${HERMES_DIRECT_RUN_EVENTS_TIMEOUT_SEC:-20}"+HERMES_STOP_ASSERT="${HERMES_STOP_ASSERT:-auto}"+HERMES_SMOKE_KEEP="${HERMES_SMOKE_KEEP:-0}"+HERMES_SMOKE_NETWORK="${HERMES_SMOKE_NETWORK:-}"+HERMES_DOCKER_ADD_HOST="${HERMES_DOCKER_ADD_HOST:-1}"+HERMES_SMOKE_STATE_DIR="${HERMES_SMOKE_STATE_DIR:-${TMPDIR:-/tmp}/paperclip-hermes-gateway-smoke-${RUN_SUFFIX}}"+HERMES_SMOKE_DIAG_DIR="${HERMES_SMOKE_DIAG_DIR:-${TMPDIR:-/tmp}/paperclip-hermes-gateway-e2e-diag-${RUN_SUFFIX}}"+HERMES_SMOKE_MODEL_PROVIDER="${HERMES_SMOKE_MODEL_PROVIDER:-}"+HERMES_SMOKE_MODEL_DEFAULT="${HERMES_SMOKE_MODEL_DEFAULT:-}"+HERMES_SMOKE_MODEL_BASE_URL="${HERMES_SMOKE_MODEL_BASE_URL:-}"+HERMES_AGENT_NAME="${HERMES_AGENT_NAME:-Hermes Gateway Smoke Agent ${RUN_SUFFIX}}"+PAPERCLIP_API_URL_FOR_HERMES="${PAPERCLIP_API_URL_FOR_HERMES:-http://host.docker.internal:3100}"+RUN_TIMEOUT_SEC="${RUN_TIMEOUT_SEC:-420}"+CASE_TIMEOUT_SEC="${CASE_TIMEOUT_SEC:-420}"+GATEWAY_READY_TIMEOUT_SEC="${GATEWAY_READY_TIMEOUT_SEC:-90}"+STRICT_CASES="${STRICT_CASES:-1}"+HERMES_PROVIDER_ENV_KEYS=(+ OPENROUTER_API_KEY+ OPENAI_API_KEY+ ANTHROPIC_API_KEY+ GEMINI_API_KEY+ GOOGLE_API_KEY+ MISTRAL_API_KEY+)++print_usage() {+ cat <<'EOF'+Hermes gateway Docker E2E smoke++Builds a fresh Hermes gateway container, verifies the gateway API directly,+joins it to Paperclip as a hermes_gateway agent, wakes that agent on a smoke+issue, verifies the issue result, captures redacted diagnostics, and cleans up+Paperclip and Docker state unless HERMES_SMOKE_KEEP=1.++Required:+ PAPERCLIP_API_URL=http://127.0.0.1:3100+ PAPERCLIP_AUTH_HEADER='Bearer <board-token>' # or PAPERCLIP_COOKIE++Common flags:+ COMPANY_ID=<uuid> or COMPANY_SELECTOR=<prefix|name|uuid>+ HERMES_VERSION=0.17.0+ HERMES_IMAGE=paperclip-hermes-gateway-smoke:local+ HERMES_GATEWAY_PORT=8642+ HERMES_GATEWAY_API_BASE_URL=http://127.0.0.1:8642+ HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642+ PAPERCLIP_API_URL_FOR_HERMES=http://host.docker.internal:3100+ HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 # dev-only non-loopback HTTP+ HERMES_SMOKE_NETWORK=<docker-network>+ HERMES_DOCKER_ADD_HOST=0|1+ HERMES_SMOKE_KEEP=1 # keep diagnostics/container+ HERMES_SMOKE_DIAG_DIR=/tmp/hermes-gateway-diag+ HERMES_SMOKE_MODEL_PROVIDER=openrouter+ HERMES_SMOKE_MODEL_DEFAULT=z-ai/glm-5.2+ HERMES_SMOKE_MODEL_BASE_URL=https://openrouter.ai/api/v1++Mode notes:+ HERMES_GATEWAY_API_BASE_URL is the URL stored on the Paperclip adapter and+ must be reachable by the Paperclip server. HERMES_GATEWAY_PROBE_URL is the URL+ this operator shell uses for direct gateway checks. They can differ for Docker+ network and reverse-proxy smoke runs.++ Raw Hermes and Paperclip API keys are redacted from logs and diagnostic files.+ The E2E helper seeds a minimal non-secret Hermes config in the fresh container+ state, including command_allowlist: execute_code so gateway/API runs do not+ pause on an interactive approval prompt.+ The generated/claimed key material is kept only in the per-run state directory,+ which is deleted on success unless HERMES_SMOKE_KEEP=1.++See doc/HERMES_GATEWAY_SMOKE.md for Docker Desktop, Linux, same-network,+LAN/private-network, and reverse-proxy/TLS examples.+EOF+}++case "${1:-}" in+ -h|--help)+ print_usage+ exit 0+ ;;+esac++AUTH_HEADERS=()+if [[ -n "${PAPERCLIP_AUTH_HEADER:-}" ]]; then+ AUTH_HEADERS+=(-H "Authorization: ${PAPERCLIP_AUTH_HEADER}")+elif [[ -n "${PAPERCLIP_API_KEY:-}" ]]; then+ AUTH_HEADERS+=(-H "Authorization: Bearer ${PAPERCLIP_API_KEY}")+fi+if [[ -n "${PAPERCLIP_COOKIE:-}" ]]; then+ AUTH_HEADERS+=(-H "Cookie: ${PAPERCLIP_COOKIE}")+ PAPERCLIP_BROWSER_ORIGIN="${PAPERCLIP_BROWSER_ORIGIN:-${PAPERCLIP_API_URL%/}}"+ AUTH_HEADERS+=(-H "Origin: ${PAPERCLIP_BROWSER_ORIGIN}" -H "Referer: ${PAPERCLIP_BROWSER_ORIGIN}/")+fi++RESPONSE_CODE=""+RESPONSE_BODY=""+AGENT_ID=""+AGENT_API_KEY=""+INVITE_ID=""+JOIN_REQUEST_ID=""+KEY_ID=""+SMOKE_ISSUE_ID=""+SMOKE_ISSUE_IDENTIFIER=""+RUN_ID=""+DIRECT_RUN_ID=""+STOP_RUN_ID=""+JOIN_OUTPUT_FILE="${HERMES_SMOKE_DIAG_DIR}/join-output.json"+KEEP_ON_EXIT="$HERMES_SMOKE_KEEP"++hash_prefix() {+ local value="$1"+ if command -v sha256sum >/dev/null 2>&1; then+ printf "%s" "$value" | sha256sum | awk '{print substr($1,1,12)}'+ elif command -v shasum >/dev/null 2>&1; then+ printf "%s" "$value" | shasum -a 256 | awk '{print substr($1,1,12)}'+ else+ printf "unavailable"+ fi+}++generate_key() {+ if command -v openssl >/dev/null 2>&1; then+ openssl rand -hex 32+ elif command -v node >/dev/null 2>&1; then+ node -e 'process.stdout.write(require("node:crypto").randomBytes(32).toString("hex"))'+ else+ fail "missing openssl or node for API_SERVER_KEY generation"+ fi+}++redact_text() {+ local text="$1"+ local secret+ for secret in \+ "${HERMES_GATEWAY_API_KEY:-}" \+ "${AGENT_API_KEY:-}" \+ "${PAPERCLIP_API_KEY:-}" \+ "${PAPERCLIP_AUTH_HEADER:-}" \+ "${PAPERCLIP_COOKIE:-}"; do+ if [[ -n "$secret" ]]; then+ text="${text//$secret/[redacted len=${#secret}]}"+ fi+ done+ local key+ for key in "${HERMES_PROVIDER_ENV_KEYS[@]}"; do+ secret="${!key-}"+ if [[ -n "$secret" ]]; then+ text="${text//$secret/[redacted len=${#secret}]}"+ fi+ done+ printf "%s" "$text"+}++url_host() {+ local url="$1"+ local rest host_port host+ rest="${url#http://}"+ rest="${rest#https://}"+ if [[ "$rest" == \[*\]* ]]; then+ host="${rest#\[}"+ host="${host%%\]*}"+ else+ host_port="${rest%%/*}"+ host="${host_port%%:*}"+ fi+ printf "%s" "$host"+}++is_loopback_http_host() {+ local host+ host="$(printf "%s" "$1" | tr '[:upper:]' '[:lower:]')"+ case "$host" in+ localhost|0.0.0.0|::1|0:0:0:0:0:0:0:1) return 0 ;;+ esac+ [[ "$host" =~ ^127\.([0-9]{1,3}\.){2}[0-9]{1,3}$ ]]+}++is_remote_plain_http() {+ local url="$1"+ [[ "$url" == http://* ]] || return 1+ ! is_loopback_http_host "$(url_host "$url")"+}++assert_gateway_api_base_url_allowed() {+ if is_remote_plain_http "$HERMES_GATEWAY_API_BASE_URL" && [[ "$HERMES_GATEWAY_ALLOW_INSECURE_HTTP" != "1" ]]; then+ fail "HERMES_GATEWAY_API_BASE_URL uses non-loopback http. Set HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 for local-only unsafe HTTP, or use HTTPS."+ fi+}++api_request() {+ local method="$1"+ local path="$2"+ local data="${3-}"+ local tmp+ tmp="$(mktemp)"++ local url+ if [[ "$path" == http://* || "$path" == https://* ]]; then+ url="$path"+ elif [[ "$path" == /api/* ]]; then+ url="${PAPERCLIP_API_URL%/}${path}"+ else+ url="${API_BASE}${path}"+ fi++ if [[ -n "$data" ]]; then+ RESPONSE_CODE="$(curl -sS -o "$tmp" -w "%{http_code}" -X "$method" "${AUTH_HEADERS[@]}" -H "Content-Type: application/json" "$url" --data "$data")"+ else+ RESPONSE_CODE="$(curl -sS -o "$tmp" -w "%{http_code}" -X "$method" "${AUTH_HEADERS[@]}" "$url")"+ fi+ RESPONSE_BODY="$(cat "$tmp")"+ rm -f "$tmp"+}++assert_status() {+ local expected="$1"+ if [[ "$RESPONSE_CODE" != "$expected" ]]; then+ redact_text "$RESPONSE_BODY" >&2+ echo >&2+ fail "expected HTTP ${expected}, got HTTP ${RESPONSE_CODE}"+ fi+}++gateway_request() {+ local method="$1"+ local path="$2"+ local data="${3-}"+ local output_file="${4-}"+ local tmp+ tmp="$(mktemp)"++ local url="${HERMES_GATEWAY_PROBE_URL%/}${path}"+ if [[ -n "$data" ]]; then+ RESPONSE_CODE="$(curl -s -o "$tmp" -w "%{http_code}" -X "$method" -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" -H "Content-Type: application/json" "$url" --data "$data" || true)"+ else+ RESPONSE_CODE="$(curl -s -o "$tmp" -w "%{http_code}" -X "$method" -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" "$url" || true)"+ fi+ RESPONSE_BODY="$(cat "$tmp")"+ if [[ -n "$output_file" ]]; then+ redact_text "$RESPONSE_BODY" > "$output_file"+ fi+ rm -f "$tmp"+}++wait_http_ready() {+ local url="$1"+ local timeout_sec="$2"+ local started now code+ started="$(date +%s)"+ while true; do+ code="$(curl -sS -o /dev/null -w "%{http_code}" -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" "$url" || true)"+ if [[ "$code" == "200" ]]; then+ return 0+ fi+ now="$(date +%s)"+ if (( now - started >= timeout_sec )); then+ return 1+ fi+ sleep 1+ done+}++require_board_auth() {+ if [[ ${#AUTH_HEADERS[@]} -eq 0 ]]; then+ fail "board/operator auth required. Set PAPERCLIP_COOKIE, PAPERCLIP_AUTH_HEADER, or a board-capable PAPERCLIP_API_KEY."+ fi+ api_request "GET" "/companies"+ if [[ "$RESPONSE_CODE" != "200" ]]; then+ redact_text "$RESPONSE_BODY" >&2+ echo >&2+ fail "board/operator auth invalid for /api/companies (HTTP ${RESPONSE_CODE})"+ fi+}++resolve_company_id() {+ if [[ -n "$COMPANY_ID" ]]; then+ log "using company ${COMPANY_ID}"+ return+ fi++ api_request "GET" "/companies"+ assert_status "200"++ if [[ -n "$COMPANY_SELECTOR" ]]; then+ COMPANY_ID="$(jq -r --arg selector "$COMPANY_SELECTOR" '+ map(select(+ (.id == $selector)+ or ((.issuePrefix // "") == $selector)+ or ((.name // "") == $selector)+ )) | .[0].id // empty+ ' <<<"$RESPONSE_BODY")"+ [[ -n "$COMPANY_ID" ]] || fail "no company matched COMPANY_SELECTOR=${COMPANY_SELECTOR}"+ else+ COMPANY_ID="$(jq -r '.[0].id // empty' <<<"$RESPONSE_BODY")"+ [[ -n "$COMPANY_ID" ]] || fail "no companies found"+ fi+ log "resolved company ${COMPANY_ID}"+}++capture_container_logs() {+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"+ docker logs --tail=2000 "$HERMES_CONTAINER_NAME" > "${HERMES_SMOKE_DIAG_DIR}/hermes-container.log" 2>&1 || true+ if [[ -s "${HERMES_SMOKE_DIAG_DIR}/hermes-container.log" ]]; then+ local redacted_tmp+ redacted_tmp="$(mktemp)"+ redact_text "$(cat "${HERMES_SMOKE_DIAG_DIR}/hermes-container.log")" > "$redacted_tmp"+ mv "$redacted_tmp" "${HERMES_SMOKE_DIAG_DIR}/hermes-container.log"+ fi+}++capture_run_diagnostics() {+ local run_id="$1"+ local label="${2:-run}"+ [[ -n "$run_id" ]] || return 0+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"++ api_request "GET" "/heartbeat-runs/${run_id}/events?limit=1000"+ if [[ "$RESPONSE_CODE" == "200" ]]; then+ redact_text "$RESPONSE_BODY" > "${HERMES_SMOKE_DIAG_DIR}/${label}-${run_id}-events.json"+ fi++ api_request "GET" "/heartbeat-runs/${run_id}/log?limitBytes=524288"+ if [[ "$RESPONSE_CODE" == "200" ]]; then+ redact_text "$RESPONSE_BODY" > "${HERMES_SMOKE_DIAG_DIR}/${label}-${run_id}-log.json"+ jq -r '.content // ""' <<<"$RESPONSE_BODY" | while IFS= read -r line; do redact_text "$line"; echo; done > "${HERMES_SMOKE_DIAG_DIR}/${label}-${run_id}-log.txt" 2>/dev/null || true+ fi+}++capture_issue_diagnostics() {+ local issue_id="$1"+ local label="${2:-issue}"+ [[ -n "$issue_id" ]] || return 0+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"++ api_request "GET" "/issues/${issue_id}"+ if [[ "$RESPONSE_CODE" == "200" ]]; then+ redact_text "$RESPONSE_BODY" > "${HERMES_SMOKE_DIAG_DIR}/${label}-${issue_id}.json"+ fi++ api_request "GET" "/issues/${issue_id}/comments"+ if [[ "$RESPONSE_CODE" == "200" ]]; then+ redact_text "$RESPONSE_BODY" > "${HERMES_SMOKE_DIAG_DIR}/${label}-${issue_id}-comments.json"+ fi+}++capture_diagnostics() {+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"+ {+ echo "runSuffix=${RUN_SUFFIX}"+ echo "companyId=${COMPANY_ID:-}"+ echo "agentId=${AGENT_ID:-}"+ echo "inviteId=${INVITE_ID:-}"+ echo "joinRequestId=${JOIN_REQUEST_ID:-}"+ echo "container=${HERMES_CONTAINER_NAME}"+ echo "image=${HERMES_IMAGE}"+ echo "gateway=${HERMES_GATEWAY_API_BASE_URL}"+ echo "gatewayProbe=${HERMES_GATEWAY_PROBE_URL}"+ echo "paperclipApiUrl=${PAPERCLIP_API_URL}"+ echo "paperclipApiUrlForHermes=${PAPERCLIP_API_URL_FOR_HERMES}"+ echo "apiServerKeySha256=$(hash_prefix "${HERMES_GATEWAY_API_KEY:-}") len=${#HERMES_GATEWAY_API_KEY}"+ echo "agentApiKeySha256=$(hash_prefix "${AGENT_API_KEY:-}") len=${#AGENT_API_KEY}"+ } > "${HERMES_SMOKE_DIAG_DIR}/summary.env"++ gateway_request "GET" "/health" "" "${HERMES_SMOKE_DIAG_DIR}/gateway-health.json" || true+ gateway_request "GET" "/v1/capabilities" "" "${HERMES_SMOKE_DIAG_DIR}/gateway-capabilities.json" || true+ capture_container_logs+ capture_issue_diagnostics "$SMOKE_ISSUE_ID" "paperclip-smoke"+ capture_run_diagnostics "$RUN_ID" "paperclip-smoke"+}++cleanup_paperclip_state() {+ [[ "$KEEP_ON_EXIT" != "1" ]] || return 0++ if [[ -n "$SMOKE_ISSUE_ID" ]]; then+ log "deleting smoke issue ${SMOKE_ISSUE_ID}"+ api_request "DELETE" "/issues/${SMOKE_ISSUE_ID}"+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "404" && "$RESPONSE_CODE" != "204" ]]; then+ warn "delete issue returned HTTP ${RESPONSE_CODE}"+ fi+ fi++ if [[ -n "$AGENT_ID" ]]; then+ log "terminating/deleting smoke agent ${AGENT_ID}"+ api_request "POST" "/agents/${AGENT_ID}/terminate" "{}"+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "404" ]]; then+ warn "terminate agent returned HTTP ${RESPONSE_CODE}"+ fi+ api_request "DELETE" "/agents/${AGENT_ID}"+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "404" && "$RESPONSE_CODE" != "204" ]]; then+ warn "delete agent returned HTTP ${RESPONSE_CODE}"+ fi+ fi++ if [[ -n "$JOIN_REQUEST_ID" && -n "$COMPANY_ID" ]]; then+ api_request "POST" "/companies/${COMPANY_ID}/join-requests/${JOIN_REQUEST_ID}/reject" "{}"+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "404" && "$RESPONSE_CODE" != "409" ]]; then+ warn "reject join request returned HTTP ${RESPONSE_CODE}"+ fi+ fi+}++cleanup_local_state() {+ [[ "$KEEP_ON_EXIT" != "1" ]] || return 0++ docker rm -f "$HERMES_CONTAINER_NAME" >/dev/null 2>&1 || true+ rm -rf "$HERMES_SMOKE_STATE_DIR"+ rm -f "$JOIN_OUTPUT_FILE"+}++on_exit() {+ local status=$?+ if [[ "$status" -ne 0 ]]; then+ KEEP_ON_EXIT=1+ warn "smoke failed; preserving diagnostics/state"+ capture_diagnostics || true+ fi++ cleanup_paperclip_state || true+ cleanup_local_state || true++ if [[ "$KEEP_ON_EXIT" == "1" ]]; then+ warn "retained diagnostics: ${HERMES_SMOKE_DIAG_DIR}"+ warn "retained state dir: ${HERMES_SMOKE_STATE_DIR}"+ warn "retained container: ${HERMES_CONTAINER_NAME}"+ fi+ exit "$status"+}+trap on_exit EXIT++build_image() {+ if [[ "$HERMES_BUILD" != "1" ]]; then+ log "HERMES_BUILD=${HERMES_BUILD}; reusing image ${HERMES_IMAGE}"+ return+ fi+ log "building Hermes gateway image ${HERMES_IMAGE} (HERMES_VERSION=${HERMES_VERSION})"+ docker build --build-arg "HERMES_VERSION=${HERMES_VERSION}" -t "$HERMES_IMAGE" "$HERMES_DOCKER_CONTEXT"+}++prepare_fresh_state() {+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"+ if [[ -e "$HERMES_SMOKE_STATE_DIR" && "$HERMES_SMOKE_KEEP" != "1" ]]; then+ rm -rf "$HERMES_SMOKE_STATE_DIR"+ fi+ mkdir -p \+ "${HERMES_SMOKE_STATE_DIR}/hermes-home" \+ "${HERMES_SMOKE_STATE_DIR}/workspace" \+ "${HERMES_SMOKE_STATE_DIR}/fake-host-home/.hermes"+ # These host-created bind mounts must be readable and writable by the+ # non-root hermes user (uid 10001) inside the container.+ chmod 777 "${HERMES_SMOKE_STATE_DIR}/hermes-home" "${HERMES_SMOKE_STATE_DIR}/workspace" || true+ echo "host hermes sentinel ${RUN_SUFFIX}" > "${HERMES_SMOKE_STATE_DIR}/fake-host-home/.hermes/host-sentinel.txt"++ if find "${HERMES_SMOKE_STATE_DIR}/hermes-home" -mindepth 1 -print -quit | grep -q .; then+ fail "Hermes state dir is not empty: ${HERMES_SMOKE_STATE_DIR}/hermes-home"+ fi+}++yaml_single_quote() {+ local value="$1"+ value="${value//\'/\'\'}"+ printf "'%s'" "$value"+}++write_hermes_model_config() {+ local has_model_config=0+ if [[ -n "$HERMES_SMOKE_MODEL_PROVIDER" || -n "$HERMES_SMOKE_MODEL_DEFAULT" || -n "$HERMES_SMOKE_MODEL_BASE_URL" ]]; then+ has_model_config=1+ fi+ if [[ "$has_model_config" == "1" && ( -z "$HERMES_SMOKE_MODEL_PROVIDER" || -z "$HERMES_SMOKE_MODEL_DEFAULT" ) ]]; then+ fail "HERMES_SMOKE_MODEL_PROVIDER and HERMES_SMOKE_MODEL_DEFAULT must be set together"+ fi++ local config_file="${HERMES_SMOKE_STATE_DIR}/hermes-home/config.yaml"+ if [[ -e "$config_file" ]]; then+ fail "Hermes model config already exists in fresh state: ${config_file}"+ fi++ {+ if [[ "$has_model_config" == "1" ]]; then+ echo "model:"+ printf " default: %s\n" "$(yaml_single_quote "$HERMES_SMOKE_MODEL_DEFAULT")"+ printf " provider: %s\n" "$(yaml_single_quote "$HERMES_SMOKE_MODEL_PROVIDER")"+ if [[ -n "$HERMES_SMOKE_MODEL_BASE_URL" ]]; then+ printf " base_url: %s\n" "$(yaml_single_quote "$HERMES_SMOKE_MODEL_BASE_URL")"+ fi+ echo "providers: {}"+ fi+ echo "command_allowlist:"+ echo "- execute_code"+ } > "$config_file"+ chmod 644 "$config_file"+ if [[ "$has_model_config" == "1" ]]; then+ log "seeded Hermes model config provider=${HERMES_SMOKE_MODEL_PROVIDER} model=${HERMES_SMOKE_MODEL_DEFAULT}"+ else+ log "seeded Hermes smoke config"+ fi+}++start_container() {+ docker rm -f "$HERMES_CONTAINER_NAME" >/dev/null 2>&1 || true++ local args=(+ run -d+ --name "$HERMES_CONTAINER_NAME"+ -p "127.0.0.1:${HERMES_GATEWAY_PORT}:8642"+ -e API_SERVER_ENABLED=true+ -e API_SERVER_KEY="$HERMES_GATEWAY_API_KEY"+ -e API_SERVER_HOST=0.0.0.0+ -e API_SERVER_PORT=8642+ -e PAPERCLIP_API_URL="$PAPERCLIP_API_URL_FOR_HERMES"+ -e NO_COLOR=1+ -v "${HERMES_SMOKE_STATE_DIR}/hermes-home:/home/hermes/.hermes"+ -v "${HERMES_SMOKE_STATE_DIR}/workspace:/home/hermes/workspace"+ )+ local provider_key+ local provider_keys=()+ for provider_key in "${HERMES_PROVIDER_ENV_KEYS[@]}"; do+ if [[ -n "${!provider_key-}" ]]; then+ args+=(-e "${provider_key}=${!provider_key}")+ provider_keys+=("$provider_key")+ fi+ done+ if [[ ${#provider_keys[@]} -gt 0 ]]; then+ log "passing Hermes inference provider env keys: ${provider_keys[*]}"+ else+ warn "no Hermes inference provider env keys set; direct run will fail unless Hermes state config already has a provider"+ fi+ if [[ -n "$HERMES_SMOKE_NETWORK" ]]; then+ args+=(--network "$HERMES_SMOKE_NETWORK")+ fi+ if [[ "$HERMES_DOCKER_ADD_HOST" == "1" ]]; then+ args+=(--add-host=host.docker.internal:host-gateway)+ fi+ args+=("$HERMES_IMAGE")++ log "starting container ${HERMES_CONTAINER_NAME}"+ docker "${args[@]}" >/dev/null+}++assert_fresh_container_state() {+ log "asserting container does not see host Hermes state"+ docker exec "$HERMES_CONTAINER_NAME" sh -lc 'test ! -e "$HERMES_HOME/host-sentinel.txt"'+ docker exec "$HERMES_CONTAINER_NAME" sh -lc 'env | sort | grep -E "^(HOME|HERMES_HOME|XDG_|API_SERVER_|PAPERCLIP_API_URL)=" || true' > "${HERMES_SMOKE_DIAG_DIR}/container-env.txt"+ docker exec "$HERMES_CONTAINER_NAME" sh -lc 'find "$HERMES_HOME" -maxdepth 2 -type f -print | sort' > "${HERMES_SMOKE_DIAG_DIR}/container-hermes-home-files-before.txt" || true+ if docker exec "$HERMES_CONTAINER_NAME" sh -lc 'env | grep -q "^PAPERCLIP_API_KEY="'; then+ fail "container unexpectedly has PAPERCLIP_API_KEY before join/key claim"+ fi+}++probe_container_to_paperclip() {+ log "probing container-to-Paperclip connectivity at ${PAPERCLIP_API_URL_FOR_HERMES}/api/health"+ if ! docker exec "$HERMES_CONTAINER_NAME" curl -fsS --max-time 8 "${PAPERCLIP_API_URL_FOR_HERMES%/}/api/health" > "${HERMES_SMOKE_DIAG_DIR}/container-paperclip-health.json"; then+ fail "Hermes container cannot reach Paperclip. Set PAPERCLIP_API_URL_FOR_HERMES to a URL reachable from inside Docker, or keep HERMES_DOCKER_ADD_HOST=1 for Linux host.docker.internal."+ fi+}++probe_gateway_readiness() {+ log "waiting for Hermes gateway health at ${HERMES_GATEWAY_PROBE_URL%/}/health"+ if [[ "$HERMES_GATEWAY_PROBE_URL" != "$HERMES_GATEWAY_API_BASE_URL" ]]; then+ log "Paperclip will store Hermes gateway URL ${HERMES_GATEWAY_API_BASE_URL}"+ fi+ wait_http_ready "${HERMES_GATEWAY_PROBE_URL%/}/health" "$GATEWAY_READY_TIMEOUT_SEC" || fail "Hermes gateway health did not become ready"++ gateway_request "GET" "/health" "" "${HERMES_SMOKE_DIAG_DIR}/gateway-health.json"+ assert_status "200"++ local wrong_code+ wrong_code="$(curl -sS -o /dev/null -w "%{http_code}" -H "Authorization: Bearer wrong-smoke-key" "${HERMES_GATEWAY_PROBE_URL%/}/v1/capabilities" || true)"+ if [[ "$wrong_code" == "200" ]]; then+ fail "Hermes protected endpoint accepted a wrong API key"+ fi+}++assert_capabilities() {+ log "asserting /v1/capabilities"+ gateway_request "GET" "/v1/capabilities" "" "${HERMES_SMOKE_DIAG_DIR}/gateway-capabilities.json"+ assert_status "200"+ if ! jq -e 'type == "object"' <<<"$RESPONSE_BODY" >/dev/null; then+ fail "capabilities response is not a JSON object"+ fi+}++poll_gateway_run_terminal() {+ local run_id="$1"+ local timeout_sec="$2"+ local label="$3"+ local started now status+ started="$(date +%s)"+ while true; do+ gateway_request "GET" "/v1/runs/${run_id}" "" "${HERMES_SMOKE_DIAG_DIR}/${label}-${run_id}-status.json"+ if [[ "$RESPONSE_CODE" == "200" ]]; then+ status="$(jq -r '.status // empty' <<<"$RESPONSE_BODY")"+ case "$status" in+ completed|failed|error|cancelled|canceled|stopped|interrupted)+ echo "$status"+ return 0+ ;;+ esac+ fi+ now="$(date +%s)"+ if (( now - started >= timeout_sec )); then+ echo "timeout"+ return 0+ fi+ sleep 2+ done+}++assert_direct_gateway_run() {+ local marker="HERMES_DIRECT_OK_${RUN_SUFFIX}"+ local payload+ payload="$(jq -nc \+ --arg marker "$marker" \+ --arg session "paperclip-smoke-direct-${RUN_SUFFIX}" \+ '{input: ("Reply with exactly " + $marker + " and no other text."), instructions: "You are running a Paperclip Hermes gateway smoke direct API assertion.", session_id: $session}')"++ log "asserting POST /v1/runs and SSE events"+ gateway_request "POST" "/v1/runs" "$payload" "${HERMES_SMOKE_DIAG_DIR}/direct-run-create.json"+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "202" ]]; then+ redact_text "$RESPONSE_BODY" >&2+ echo >&2+ fail "expected HTTP 200 or 202, got HTTP ${RESPONSE_CODE}"+ fi+ DIRECT_RUN_ID="$(jq -r '.run_id // .runId // .id // empty' <<<"$RESPONSE_BODY")"+ [[ -n "$DIRECT_RUN_ID" ]] || fail "direct run creation did not return run id"++ local events_file="${HERMES_SMOKE_DIAG_DIR}/direct-run-${DIRECT_RUN_ID}-events.sse"+ curl -sS --max-time "$HERMES_DIRECT_RUN_EVENTS_TIMEOUT_SEC" -N \+ -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" \+ "${HERMES_GATEWAY_PROBE_URL%/}/v1/runs/${DIRECT_RUN_ID}/events" \+ > "${events_file}.raw" || true+ redact_text "$(cat "${events_file}.raw")" > "$events_file"+ rm -f "${events_file}.raw"+ local events_seen=0+ if grep -Eq '(^event:|^data:)' "$events_file"; then+ events_seen=1+ else+ warn "SSE stream produced no event/data frames within ${HERMES_DIRECT_RUN_EVENTS_TIMEOUT_SEC}s; polling direct run status"+ fi++ local status+ status="$(poll_gateway_run_terminal "$DIRECT_RUN_ID" "$HERMES_DIRECT_RUN_TIMEOUT_SEC" "direct-run")"+ log "direct Hermes run ${DIRECT_RUN_ID} status=${status}"+ [[ "$status" == "completed" ]] || fail "direct Hermes run did not complete successfully (status=${status})"+ if [[ "$events_seen" != "1" ]]; then+ warn "direct Hermes run completed, but the live SSE probe was quiet"+ fi+}++assert_stop_behavior_if_deterministic() {+ [[ "$HERMES_STOP_ASSERT" != "0" ]] || {+ log "HERMES_STOP_ASSERT=0; skipping /stop assertion"+ return+ }++ local payload+ payload="$(jq -nc \+ --arg session "paperclip-smoke-stop-${RUN_SUFFIX}" \+ '{input: "Wait until stopped. If you cannot wait, emit a short acknowledgement.", instructions: "This run exists only to verify the Hermes gateway stop endpoint.", session_id: $session}')"++ log "probing /stop behavior (mode=${HERMES_STOP_ASSERT})"+ gateway_request "POST" "/v1/runs" "$payload" "${HERMES_SMOKE_DIAG_DIR}/stop-run-create.json"+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "202" ]]; then+ redact_text "$RESPONSE_BODY" >&2+ echo >&2+ fail "expected HTTP 200 or 202, got HTTP ${RESPONSE_CODE}"+ fi+ STOP_RUN_ID="$(jq -r '.run_id // .runId // .id // empty' <<<"$RESPONSE_BODY")"+ [[ -n "$STOP_RUN_ID" ]] || fail "stop test run creation did not return run id"++ gateway_request "POST" "/v1/runs/${STOP_RUN_ID}/stop" "{}" "${HERMES_SMOKE_DIAG_DIR}/stop-run-stop-response.json"+ if [[ "$RESPONSE_CODE" != "200" && "$RESPONSE_CODE" != "202" && "$RESPONSE_CODE" != "204" ]]; then+ if [[ "$HERMES_STOP_ASSERT" == "auto" ]]; then+ warn "/stop returned HTTP ${RESPONSE_CODE}; treating stop assertion as non-deterministic"+ return+ fi+ fail "/stop returned HTTP ${RESPONSE_CODE}"+ fi++ local status+ status="$(poll_gateway_run_terminal "$STOP_RUN_ID" 45 "stop-run")"+ case "$status" in+ cancelled|canceled|stopped|interrupted)+ log "stop run ${STOP_RUN_ID} reached ${status}"+ ;;+ completed)+ if [[ "$HERMES_STOP_ASSERT" == "auto" ]]; then+ warn "stop run completed before cancellation could be observed; treating stop assertion as non-deterministic"+ else+ fail "stop run completed instead of stopping"+ fi+ ;;+ *)+ if [[ "$HERMES_STOP_ASSERT" == "auto" ]]; then+ warn "stop run terminal status ${status}; treating stop assertion as non-deterministic"+ else+ fail "stop run did not reach a stopped/cancelled terminal status (status=${status})"+ fi+ ;;+ esac+}++join_hermes_agent() {+ log "running join-only smoke helper"+ local join_log="${HERMES_SMOKE_DIAG_DIR}/hermes-gateway-join.log"+ HERMES_AGENT_NAME="$HERMES_AGENT_NAME" \+ HERMES_GATEWAY_API_BASE_URL="$HERMES_GATEWAY_API_BASE_URL" \+ HERMES_GATEWAY_PROBE_URL="$HERMES_GATEWAY_PROBE_URL" \+ HERMES_GATEWAY_API_KEY="$HERMES_GATEWAY_API_KEY" \+ HERMES_GATEWAY_ALLOW_INSECURE_HTTP="$HERMES_GATEWAY_ALLOW_INSECURE_HTTP" \+ HERMES_GATEWAY_SESSION_KEY_STRATEGY="$HERMES_GATEWAY_SESSION_KEY_STRATEGY" \+ HERMES_GATEWAY_TIMEOUT_SEC="$HERMES_ADAPTER_TIMEOUT_SEC" \+ PAPERCLIP_API_URL="$PAPERCLIP_API_URL" \+ PAPERCLIP_API_URL_FOR_HERMES="$PAPERCLIP_API_URL_FOR_HERMES" \+ PAPERCLIP_AUTH_HEADER="${PAPERCLIP_AUTH_HEADER:-}" \+ PAPERCLIP_API_KEY="${PAPERCLIP_API_KEY:-}" \+ PAPERCLIP_COOKIE="${PAPERCLIP_COOKIE:-}" \+ COMPANY_ID="$COMPANY_ID" \+ COMPANY_SELECTOR="$COMPANY_SELECTOR" \+ HERMES_JOIN_OUTPUT_FILE="$JOIN_OUTPUT_FILE" \+ bash scripts/smoke/hermes-gateway-join.sh > "${join_log}.raw" 2>&1 || {+ redact_text "$(cat "${join_log}.raw")" > "$join_log"+ rm -f "${join_log}.raw"+ fail "join helper failed; see ${join_log}"+ }+ redact_text "$(cat "${join_log}.raw")" > "$join_log"+ rm -f "${join_log}.raw"++ [[ -f "$JOIN_OUTPUT_FILE" ]] || fail "join helper did not write ${JOIN_OUTPUT_FILE}"+ AGENT_ID="$(jq -r '.agentId // empty' "$JOIN_OUTPUT_FILE")"+ AGENT_API_KEY="$(jq -r '.agentApiKey // empty' "$JOIN_OUTPUT_FILE")"+ INVITE_ID="$(jq -r '.inviteId // empty' "$JOIN_OUTPUT_FILE")"+ JOIN_REQUEST_ID="$(jq -r '.joinRequestId // empty' "$JOIN_OUTPUT_FILE")"+ KEY_ID="$(jq -r '.keyId // empty' "$JOIN_OUTPUT_FILE")"+ [[ -n "$AGENT_ID" && -n "$AGENT_API_KEY" ]] || fail "join output missing agent id or API key"+ log "joined Hermes gateway agent ${AGENT_ID} keyId=${KEY_ID} agentKeySha256=$(hash_prefix "$AGENT_API_KEY")"+}++install_claimed_key_in_container() {+ log "placing newly claimed Paperclip key in container workspace"+ local key_file="${HERMES_SMOKE_STATE_DIR}/workspace/paperclip-claimed-api-key.json"+ jq -nc --arg token "$AGENT_API_KEY" '{token:$token,apiKey:$token}' > "$key_file"+ # The host-created bind-mounted file must be readable by the non-root hermes+ # user inside the container. The state dir is still per-run and deleted on+ # success unless HERMES_SMOKE_KEEP=1.+ chmod 644 "$key_file"+ docker exec "$HERMES_CONTAINER_NAME" sh -lc 'test -f /home/hermes/workspace/paperclip-claimed-api-key.json && test ! -e "$HERMES_HOME/host-sentinel.txt"'+}++patch_agent_instructions_with_claimed_key() {+ log "patching Hermes agent instructions with claimed Paperclip API context"+ api_request "GET" "/agents/${AGENT_ID}"+ assert_status "200"++ local instructions patch_payload+ instructions="For this smoke run only, call Paperclip at ${PAPERCLIP_API_URL_FOR_HERMES}. Read /home/hermes/workspace/paperclip-claimed-api-key.json and use its token as PAPERCLIP_API_KEY for Paperclip API requests. Do not reveal this key. When mutating Paperclip, include X-Paperclip-Run-Id with the current Paperclip run id when available."+ patch_payload="$(jq -c --arg instructions "$instructions" '+ {adapterConfig: ((.adapterConfig // {}) + {instructions: $instructions})}+ ' <<<"$RESPONSE_BODY")"+ api_request "PATCH" "/agents/${AGENT_ID}" "$patch_payload"+ assert_status "200"+}++create_smoke_issue() {+ local marker="HERMES_PAPERCLIP_E2E_OK_${RUN_SUFFIX}"+ local title="[Hermes Gateway Smoke] ${RUN_SUFFIX}"+ local description+ description="Hermes gateway full Docker e2e smoke.\n\n1. Read this issue.\n2. Post a Paperclip issue comment containing exactly: ${marker}\n3. Mark this issue done.\n\nUse the Paperclip API URL and key provided in your run instructions. Do not reveal secrets."++ local payload+ payload="$(jq -nc \+ --arg title "$title" \+ --arg description "$description" \+ --arg assignee "$AGENT_ID" \+ '{title:$title,description:$description,status:"todo",priority:"high",assigneeAgentId:$assignee}')"+ api_request "POST" "/companies/${COMPANY_ID}/issues" "$payload"+ assert_status "201"+ SMOKE_ISSUE_ID="$(jq -r '.id // empty' <<<"$RESPONSE_BODY")"+ SMOKE_ISSUE_IDENTIFIER="$(jq -r '.identifier // empty' <<<"$RESPONSE_BODY")"+ [[ -n "$SMOKE_ISSUE_ID" ]] || fail "smoke issue create missing id"+ log "created smoke issue ${SMOKE_ISSUE_ID} (${SMOKE_ISSUE_IDENTIFIER})"+ echo "$marker" > "${HERMES_SMOKE_DIAG_DIR}/paperclip-marker.txt"+}++trigger_wakeup() {+ local payload+ payload="$(jq -nc --arg issueId "$SMOKE_ISSUE_ID" '{source:"on_demand",triggerDetail:"manual",reason:"hermes_gateway_docker_e2e_smoke",payload:{issueId:$issueId,taskId:$issueId}}')"+ api_request "POST" "/agents/${AGENT_ID}/wakeup" "$payload"+ if [[ "$RESPONSE_CODE" != "202" ]]; then+ redact_text "$RESPONSE_BODY" >&2+ echo >&2+ fail "wakeup failed (HTTP ${RESPONSE_CODE})"+ fi+ RUN_ID="$(jq -r '.id // empty' <<<"$RESPONSE_BODY")"+ [[ -n "$RUN_ID" ]] || fail "wakeup response missing run id"+ log "triggered Paperclip run ${RUN_ID}"+}++get_run_status() {+ local run_id="$1"+ api_request "GET" "/companies/${COMPANY_ID}/heartbeat-runs?agentId=${AGENT_ID}&limit=200"+ if [[ "$RESPONSE_CODE" != "200" ]]; then+ echo ""+ return 0+ fi+ jq -r --arg runId "$run_id" '.[] | select(.id == $runId) | .status' <<<"$RESPONSE_BODY" | head -n1+}++wait_for_run_terminal() {+ local run_id="$1"+ local timeout_sec="$2"+ local started now status+ started="$(date +%s)"+ while true; do+ status="$(get_run_status "$run_id")"+ if [[ "$status" == "succeeded" || "$status" == "failed" || "$status" == "timed_out" || "$status" == "cancelled" ]]; then+ echo "$status"+ return+ fi+ now="$(date +%s)"+ if (( now - started >= timeout_sec )); then+ echo "timeout"+ return+ fi+ sleep 3+ done+}++get_issue_status() {+ local issue_id="$1"+ api_request "GET" "/issues/${issue_id}"+ if [[ "$RESPONSE_CODE" != "200" ]]; then+ echo ""+ return 0+ fi+ jq -r '.status // empty' <<<"$RESPONSE_BODY"+}++wait_for_issue_terminal() {+ local issue_id="$1"+ local timeout_sec="$2"+ local started now status+ started="$(date +%s)"+ while true; do+ status="$(get_issue_status "$issue_id")"+ if [[ "$status" == "done" || "$status" == "blocked" || "$status" == "cancelled" ]]; then+ echo "$status"+ return+ fi+ now="$(date +%s)"+ if (( now - started >= timeout_sec )); then+ echo "timeout"+ return+ fi+ sleep 3+ done+}++issue_comments_contain() {+ local issue_id="$1"+ local marker="$2"+ api_request "GET" "/issues/${issue_id}/comments"+ if [[ "$RESPONSE_CODE" != "200" ]]; then+ echo "false"+ return+ fi+ jq -r --arg marker "$marker" '[.[] | (.body // "") | contains($marker)] | any' <<<"$RESPONSE_BODY"+}++assert_paperclip_wake_success() {+ local marker+ marker="$(cat "${HERMES_SMOKE_DIAG_DIR}/paperclip-marker.txt")"++ trigger_wakeup+ local run_status issue_status marker_found+ run_status="$(wait_for_run_terminal "$RUN_ID" "$RUN_TIMEOUT_SEC")"+ log "Paperclip run ${RUN_ID} status=${run_status}"+ issue_status="$(wait_for_issue_terminal "$SMOKE_ISSUE_ID" "$CASE_TIMEOUT_SEC")"+ marker_found="$(issue_comments_contain "$SMOKE_ISSUE_ID" "$marker")"+ log "smoke issue status=${issue_status} marker_found=${marker_found}"++ if [[ "$run_status" != "succeeded" || "$issue_status" != "done" || "$marker_found" != "true" ]]; then+ capture_diagnostics+ fi+ if [[ "$STRICT_CASES" == "1" ]]; then+ [[ "$run_status" == "succeeded" ]] || fail "Paperclip Hermes gateway run did not succeed"+ [[ "$issue_status" == "done" ]] || fail "smoke issue did not reach done"+ [[ "$marker_found" == "true" ]] || fail "smoke marker was not found in issue comments"+ fi+}++scan_diagnostics_for_secret_leaks() {+ log "scanning diagnostics for raw secret leaks"+ local secrets=()+ [[ -n "$HERMES_GATEWAY_API_KEY" ]] && secrets+=("$HERMES_GATEWAY_API_KEY")+ [[ -n "$AGENT_API_KEY" ]] && secrets+=("$AGENT_API_KEY")+ local key+ for key in "${HERMES_PROVIDER_ENV_KEYS[@]}"; do+ [[ -n "${!key-}" ]] && secrets+=("${!key}")+ done+ [[ ${#secrets[@]} -gt 0 ]] || return+ local file+ while IFS= read -r file; do+ [[ "$file" == "$JOIN_OUTPUT_FILE" ]] && continue+ local secret+ for secret in "${secrets[@]}"; do+ if grep -Fq "$secret" "$file"; then+ fail "raw secret leaked in diagnostics file ${file}"+ fi+ done+ done < <(find "$HERMES_SMOKE_DIAG_DIR" -type f -print)+}++main() {+ log "starting Hermes gateway Docker E2E smoke"+ mkdir -p "$HERMES_SMOKE_DIAG_DIR"+ log "diagnostics dir: ${HERMES_SMOKE_DIAG_DIR}"++ require_cmd curl+ require_cmd docker+ require_cmd jq++ if [[ -z "$HERMES_GATEWAY_API_KEY" ]]; then+ HERMES_GATEWAY_API_KEY="$(generate_key)"+ fi+ log "Hermes API key sha256=$(hash_prefix "$HERMES_GATEWAY_API_KEY") len=${#HERMES_GATEWAY_API_KEY}"+ assert_gateway_api_base_url_allowed++ api_request "GET" "/health"+ assert_status "200"+ log "Paperclip health deploymentMode=$(jq -r '.deploymentMode // "unknown"' <<<"$RESPONSE_BODY") exposure=$(jq -r '.deploymentExposure // "unknown"' <<<"$RESPONSE_BODY")"+ require_board_auth+ resolve_company_id++ prepare_fresh_state+ write_hermes_model_config+ build_image+ start_container+ assert_fresh_container_state+ probe_container_to_paperclip+ probe_gateway_readiness+ assert_capabilities+ assert_direct_gateway_run+ assert_stop_behavior_if_deterministic+ join_hermes_agent+ install_claimed_key_in_container+ patch_agent_instructions_with_claimed_key+ create_smoke_issue+ assert_paperclip_wake_success+ capture_diagnostics+ scan_diagnostics_for_secret_leaks++ log "success"+ log "companyId=${COMPANY_ID}"+ log "agentId=${AGENT_ID}"+ log "inviteId=${INVITE_ID}"+ log "joinRequestId=${JOIN_REQUEST_ID}"+ log "issueId=${SMOKE_ISSUE_ID}"+ log "issueIdentifier=${SMOKE_ISSUE_IDENTIFIER}"+ log "runId=${RUN_ID}"+ log "directHermesRunId=${DIRECT_RUN_ID}"+ log "diagnostics=${HERMES_SMOKE_DIAG_DIR}"+}++main "$@"diff --git a/scripts/smoke/hermes-gateway-join.sh b/scripts/smoke/hermes-gateway-join.shnew file mode 100755index 0000000000..b646d97043--- /dev/null+++ b/scripts/smoke/hermes-gateway-join.sh@@ -0,0 +1,450 @@+#!/usr/bin/env bash+set -euo pipefail++log() {+ echo "[hermes-gateway-join] $*"+}++warn() {+ echo "[hermes-gateway-join] WARN: $*" >&2+}++fail() {+ echo "[hermes-gateway-join] ERROR: $*" >&2+ exit 1+}++require_cmd() {+ local cmd="$1"+ command -v "$cmd" >/dev/null 2>&1 || fail "missing required command: ${cmd}"+}++require_cmd curl+require_cmd jq++PAPERCLIP_API_URL="${PAPERCLIP_API_URL:-http://localhost:3100}"+API_BASE="${PAPERCLIP_API_URL%/}/api"+COMPANY_ID="${COMPANY_ID:-${PAPERCLIP_COMPANY_ID:-}}"+COMPANY_SELECTOR="${COMPANY_SELECTOR:-}"++HERMES_AGENT_NAME="${HERMES_AGENT_NAME:-Hermes Gateway Smoke Agent}"+HERMES_GATEWAY_API_BASE_URL="${HERMES_GATEWAY_API_BASE_URL:-http://127.0.0.1:${HERMES_GATEWAY_PORT:-8642}}"+HERMES_GATEWAY_PROBE_URL="${HERMES_GATEWAY_PROBE_URL:-$HERMES_GATEWAY_API_BASE_URL}"+HERMES_GATEWAY_API_KEY="${HERMES_GATEWAY_API_KEY:-${API_SERVER_KEY:-}}"+HERMES_GATEWAY_ALLOW_INSECURE_HTTP="${HERMES_GATEWAY_ALLOW_INSECURE_HTTP:-0}"+HERMES_GATEWAY_SESSION_KEY_STRATEGY="${HERMES_GATEWAY_SESSION_KEY_STRATEGY:-issue}"+HERMES_GATEWAY_TIMEOUT_SEC="${HERMES_GATEWAY_TIMEOUT_SEC:-180}"+PAPERCLIP_API_URL_FOR_HERMES="${PAPERCLIP_API_URL_FOR_HERMES:-}"+GATEWAY_PROBE_TIMEOUT_SEC="${GATEWAY_PROBE_TIMEOUT_SEC:-4}"+HERMES_JOIN_OUTPUT_FILE="${HERMES_JOIN_OUTPUT_FILE:-}"++print_usage() {+ cat <<'EOF'+Hermes gateway join smoke++Creates a Hermes gateway agent from an agent-only Paperclip invite, approves the+join request, claims the one-time Paperclip API key, and verifies the stored+adapter config without printing raw secrets.++Required:+ PAPERCLIP_API_URL=http://127.0.0.1:3100+ PAPERCLIP_AUTH_HEADER='Bearer <board-token>' # or PAPERCLIP_COOKIE+ HERMES_GATEWAY_API_KEY=<API_SERVER_KEY>++Common flags:+ COMPANY_ID=<uuid> or COMPANY_SELECTOR=<prefix|name|uuid>+ HERMES_GATEWAY_API_BASE_URL=http://127.0.0.1:8642+ HERMES_GATEWAY_PROBE_URL=http://127.0.0.1:8642+ PAPERCLIP_API_URL_FOR_HERMES=http://host.docker.internal:3100+ HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 # dev-only non-loopback HTTP+ HERMES_GATEWAY_SESSION_KEY_STRATEGY=issue|agent|run|none+ HERMES_JOIN_OUTPUT_FILE=/secure/path/join-output.json++Notes:+ HERMES_GATEWAY_API_BASE_URL is stored on the Paperclip adapter and must be+ reachable by the Paperclip server. HERMES_GATEWAY_PROBE_URL is only used by+ this operator shell to preflight /health, which is useful when Paperclip talks+ to the gateway over a Docker network name but the operator probes localhost.++ Raw API keys are redacted from logs. HERMES_JOIN_OUTPUT_FILE contains the+ claimed Paperclip agent API key and is written chmod 600.++See doc/HERMES_GATEWAY_SMOKE.md for Docker Desktop, Linux, same-network,+LAN/private-network, and reverse-proxy/TLS examples.+EOF+}++case "${1:-}" in+ -h|--help)+ print_usage+ exit 0+ ;;+esac++AUTH_HEADERS=()+if [[ -n "${PAPERCLIP_AUTH_HEADER:-}" ]]; then+ AUTH_HEADERS+=(-H "Authorization: ${PAPERCLIP_AUTH_HEADER}")+elif [[ -n "${PAPERCLIP_API_KEY:-}" ]]; then+ AUTH_HEADERS+=(-H "Authorization: Bearer ${PAPERCLIP_API_KEY}")+fi+if [[ -n "${PAPERCLIP_COOKIE:-}" ]]; then+ AUTH_HEADERS+=(-H "Cookie: ${PAPERCLIP_COOKIE}")+fi++RESPONSE_CODE=""+RESPONSE_BODY=""+CLAIM_SECRET=""+AGENT_API_KEY=""++hash_prefix() {+ local value="$1"+ if command -v sha256sum >/dev/null 2>&1; then+ printf "%s" "$value" | sha256sum | awk '{print substr($1,1,12)}'+ elif command -v shasum >/dev/null 2>&1; then+ printf "%s" "$value" | shasum -a 256 | awk '{print substr($1,1,12)}'+ else+ printf "unavailable"+ fi+}++redact_text() {+ local text="$1"+ local secret+ for secret in "${HERMES_GATEWAY_API_KEY:-}" "${CLAIM_SECRET:-}" "${AGENT_API_KEY:-}" "${PAPERCLIP_AUTH_HEADER:-}" "${PAPERCLIP_COOKIE:-}" "${PAPERCLIP_API_KEY:-}"; do+ if [[ -n "$secret" ]]; then+ text="${text//$secret/[redacted len=${#secret}]}"+ fi+ done+ printf "%s" "$text"+}++print_response_error() {+ redact_text "$RESPONSE_BODY" >&2+ echo >&2+}++api_request() {+ local method="$1"+ local path="$2"+ local data="${3-}"+ local tmp+ tmp="$(mktemp)"++ local url+ if [[ "$path" == http://* || "$path" == https://* ]]; then+ url="$path"+ elif [[ "$path" == /api/* ]]; then+ url="${PAPERCLIP_API_URL%/}${path}"+ else+ url="${API_BASE}${path}"+ fi++ if [[ -n "$data" ]]; then+ RESPONSE_CODE="$(curl -sS -o "$tmp" -w "%{http_code}" -X "$method" "${AUTH_HEADERS[@]}" -H "Content-Type: application/json" "$url" --data "$data")"+ else+ RESPONSE_CODE="$(curl -sS -o "$tmp" -w "%{http_code}" -X "$method" "${AUTH_HEADERS[@]}" "$url")"+ fi+ RESPONSE_BODY="$(cat "$tmp")"+ rm -f "$tmp"+}++assert_status() {+ local expected="$1"+ if [[ "$RESPONSE_CODE" != "$expected" ]]; then+ print_response_error+ fail "expected HTTP ${expected}, got HTTP ${RESPONSE_CODE}"+ fi+}++assert_json_has_string() {+ local jq_expr="$1"+ local value+ value="$(jq -r "$jq_expr // empty" <<<"$RESPONSE_BODY")"+ if [[ -z "$value" ]]; then+ print_response_error+ fail "expected JSON string at ${jq_expr}"+ fi+ echo "$value"+}++fail_board_auth_required() {+ local operation="$1"+ print_response_error+ cat >&2 <<EOF+[hermes-gateway-join] ERROR: ${operation} requires board/operator auth.++Provide one of:+ PAPERCLIP_AUTH_HEADER="Bearer <board-token>"+ PAPERCLIP_COOKIE="<board-session-cookie>"++Current auth context appears insufficient (HTTP ${RESPONSE_CODE}).+EOF+ exit 1+}++is_remote_plain_http() {+ local url="$1"+ [[ "$url" == http://* ]] || return 1+ ! is_loopback_http_host "$(url_host "$url")"+}++url_host() {+ local url="$1"+ local rest host_port host+ rest="${url#http://}"+ rest="${rest#https://}"+ if [[ "$rest" == \[*\]* ]]; then+ host="${rest#\[}"+ host="${host%%\]*}"+ else+ host_port="${rest%%/*}"+ host="${host_port%%:*}"+ fi+ printf "%s" "$host"+}++is_loopback_http_host() {+ local host+ host="$(printf "%s" "$1" | tr '[:upper:]' '[:lower:]')"+ case "$host" in+ localhost|0.0.0.0|::1|0:0:0:0:0:0:0:1) return 0 ;;+ esac+ [[ "$host" =~ ^127\.([0-9]{1,3}\.){2}[0-9]{1,3}$ ]]+}++strip_trailing_slash() {+ local value="$1"+ while [[ "$value" == */ && "$value" != "http://" && "$value" != "https://" ]]; do+ value="${value%/}"+ done+ printf "%s" "$value"+}++resolve_company_id() {+ if [[ -n "$COMPANY_ID" ]]; then+ return+ fi++ log "resolving company id"+ api_request "GET" "/companies"+ if [[ "$RESPONSE_CODE" == "401" || "$RESPONSE_CODE" == "403" ]]; then+ fail_board_auth_required "Company resolution"+ fi+ assert_status "200"++ if [[ -n "$COMPANY_SELECTOR" ]]; then+ COMPANY_ID="$(jq -r --arg selector "$COMPANY_SELECTOR" '+ map(select(+ (.id == $selector)+ or ((.issuePrefix // "") == $selector)+ or ((.name // "") == $selector)+ )) | .[0].id // empty+ ' <<<"$RESPONSE_BODY")"+ [[ -n "$COMPANY_ID" ]] || fail "no company matched COMPANY_SELECTOR=${COMPANY_SELECTOR}"+ else+ COMPANY_ID="$(jq -r '.[0].id // empty' <<<"$RESPONSE_BODY")"+ [[ -n "$COMPANY_ID" ]] || fail "no companies found; create one before running smoke test"+ fi+}++assert_onboarding_contains() {+ local body="$1"+ local needle="$2"+ if ! grep -Fq "$needle" <<<"$body"; then+ echo "$body" >&2+ fail "onboarding response missing expected text: ${needle}"+ fi+}++probe_hermes_gateway() {+ [[ -n "$HERMES_GATEWAY_API_BASE_URL" ]] || fail "HERMES_GATEWAY_API_BASE_URL is required"+ [[ -n "$HERMES_GATEWAY_PROBE_URL" ]] || fail "HERMES_GATEWAY_PROBE_URL is required"+ [[ -n "$HERMES_GATEWAY_API_KEY" ]] || fail "HERMES_GATEWAY_API_KEY or API_SERVER_KEY is required before any Paperclip state is mutated"++ if is_remote_plain_http "$HERMES_GATEWAY_API_BASE_URL" && [[ "$HERMES_GATEWAY_ALLOW_INSECURE_HTTP" != "1" ]]; then+ fail "HERMES_GATEWAY_API_BASE_URL uses non-loopback http. Set HERMES_GATEWAY_ALLOW_INSECURE_HTTP=1 for local-only unsafe HTTP, or use HTTPS."+ fi++ local health_url="${HERMES_GATEWAY_PROBE_URL%/}/health"+ log "probing Hermes gateway health at ${health_url} with apiKey sha256=$(hash_prefix "$HERMES_GATEWAY_API_KEY") len=${#HERMES_GATEWAY_API_KEY}"+ if [[ "$HERMES_GATEWAY_PROBE_URL" != "$HERMES_GATEWAY_API_BASE_URL" ]]; then+ log "Paperclip will store Hermes gateway URL ${HERMES_GATEWAY_API_BASE_URL}"+ fi+ local code+ code="$(curl -sS -o /dev/null -w "%{http_code}" --max-time "$GATEWAY_PROBE_TIMEOUT_SEC" -H "Authorization: Bearer ${HERMES_GATEWAY_API_KEY}" "$health_url" || true)"+ if [[ "$code" != "200" ]]; then+ fail "Hermes gateway health probe failed before mutating Paperclip state: ${health_url} returned HTTP ${code}. Start Hermes with API_SERVER_ENABLED=true API_SERVER_KEY=<key> hermes gateway run --replace --accept-hooks, or set HERMES_GATEWAY_API_BASE_URL/HERMES_GATEWAY_API_KEY."+ fi+}++log "checking Paperclip health"+api_request "GET" "/health"+assert_status "200"+log "deployment mode=$(jq -r '.deploymentMode // "unknown"' <<<"$RESPONSE_BODY") exposure=$(jq -r '.deploymentExposure // "unknown"' <<<"$RESPONSE_BODY")"++resolve_company_id+probe_hermes_gateway++log "creating agent-only invite for company ${COMPANY_ID}"+INVITE_PAYLOAD="$(jq -nc '{allowedJoinTypes:"agent"}')"+api_request "POST" "/companies/${COMPANY_ID}/invites" "$INVITE_PAYLOAD"+if [[ "$RESPONSE_CODE" == "401" || "$RESPONSE_CODE" == "403" ]]; then+ fail_board_auth_required "Invite creation"+fi+assert_status "201"+INVITE_TOKEN="$(assert_json_has_string '.token')"+INVITE_ID="$(assert_json_has_string '.id')"+log "created invite ${INVITE_ID}"++log "verifying onboarding JSON and text endpoints"+api_request "GET" "/invites/${INVITE_TOKEN}/onboarding"+assert_status "200"+ONBOARDING_JSON="$RESPONSE_BODY"+ONBOARDING_TEXT_PATH="$(jq -r '.invite.onboardingTextPath // empty' <<<"$ONBOARDING_JSON")"+[[ -n "$ONBOARDING_TEXT_PATH" ]] || fail "onboarding manifest missing invite.onboardingTextPath"+assert_onboarding_contains "$ONBOARDING_JSON" "hermes_gateway"+assert_onboarding_contains "$ONBOARDING_JSON" "API_SERVER_ENABLED=true"+assert_onboarding_contains "$ONBOARDING_JSON" "API_SERVER_KEY"+assert_onboarding_contains "$ONBOARDING_JSON" "agentDefaultsPayload"++api_request "GET" "/invites/${INVITE_TOKEN}/onboarding.txt"+assert_status "200"+ONBOARDING_TEXT="$RESPONSE_BODY"+assert_onboarding_contains "$ONBOARDING_TEXT" 'adapterType: "hermes_gateway"'+assert_onboarding_contains "$ONBOARDING_TEXT" "API_SERVER_ENABLED=true"+assert_onboarding_contains "$ONBOARDING_TEXT" "API_SERVER_KEY"+assert_onboarding_contains "$ONBOARDING_TEXT" "hermes gateway run --replace --accept-hooks"+assert_onboarding_contains "$ONBOARDING_TEXT" "agentDefaultsPayload.apiBaseUrl"++JOIN_PAYLOAD="$(jq -nc \+ --arg name "$HERMES_AGENT_NAME" \+ --arg apiBaseUrl "$HERMES_GATEWAY_API_BASE_URL" \+ --arg apiKey "$HERMES_GATEWAY_API_KEY" \+ --arg paperclipApiUrl "$PAPERCLIP_API_URL_FOR_HERMES" \+ --arg sessionKeyStrategy "$HERMES_GATEWAY_SESSION_KEY_STRATEGY" \+ --argjson timeoutSec "$HERMES_GATEWAY_TIMEOUT_SEC" \+ --argjson allowInsecure "$(if [[ "$HERMES_GATEWAY_ALLOW_INSECURE_HTTP" == "1" ]]; then echo true; else echo false; fi)" \+ '{+ requestType: "agent",+ agentName: $name,+ adapterType: "hermes_gateway",+ capabilities: "Hermes gateway Docker smoke harness",+ agentDefaultsPayload: {+ apiBaseUrl: $apiBaseUrl,+ apiKey: $apiKey,+ sessionKeyStrategy: $sessionKeyStrategy,+ timeoutSec: $timeoutSec+ }+ }+ | if $paperclipApiUrl != "" then .agentDefaultsPayload.paperclipApiUrl = $paperclipApiUrl else . end+ | if $allowInsecure then .agentDefaultsPayload.dangerouslyAllowInsecureRemoteHttp = true else . end')"++log "submitting Hermes gateway agent join request"+api_request "POST" "/invites/${INVITE_TOKEN}/accept" "$JOIN_PAYLOAD"+if [[ "$RESPONSE_CODE" != "202" ]]; then+ print_response_error+fi+assert_status "202"+JOIN_REQUEST_ID="$(assert_json_has_string '.id')"+CLAIM_SECRET="$(assert_json_has_string '.claimSecret')"+CLAIM_API_PATH="$(assert_json_has_string '.claimApiKeyPath')"+DIAGNOSTICS_JSON="$(jq -c '.diagnostics // []' <<<"$RESPONSE_BODY")"+if [[ "$DIAGNOSTICS_JSON" != "[]" ]]; then+ log "join diagnostics: $(redact_text "$DIAGNOSTICS_JSON")"+fi++if is_remote_plain_http "$HERMES_GATEWAY_API_BASE_URL"; then+ if ! jq -e '[.diagnostics[]? | select(.code == "hermes_gateway_plain_http_remote_unsafe_allowed")] | length > 0' <<<"$RESPONSE_BODY" >/dev/null; then+ fail "expected hermes_gateway_plain_http_remote_unsafe_allowed diagnostic for non-loopback HTTP join"+ fi+fi++log "approving join request ${JOIN_REQUEST_ID}"+api_request "POST" "/companies/${COMPANY_ID}/join-requests/${JOIN_REQUEST_ID}/approve" "{}"+if [[ "$RESPONSE_CODE" == "401" || "$RESPONSE_CODE" == "403" ]]; then+ fail_board_auth_required "Join approval"+fi+assert_status "200"+CREATED_AGENT_ID="$(assert_json_has_string '.createdAgentId')"++log "verifying invalid claim secret is rejected"+api_request "POST" "/join-requests/${JOIN_REQUEST_ID}/claim-api-key" '{"claimSecret":"invalid-smoke-secret-value"}'+if [[ "$RESPONSE_CODE" == "201" ]]; then+ fail "invalid claim secret unexpectedly succeeded"+fi++log "claiming API key with one-time claim secret"+CLAIM_PAYLOAD="$(jq -nc --arg secret "$CLAIM_SECRET" '{claimSecret:$secret}')"+api_request "POST" "$CLAIM_API_PATH" "$CLAIM_PAYLOAD"+assert_status "201"+AGENT_API_KEY="$(assert_json_has_string '.token')"+KEY_ID="$(assert_json_has_string '.keyId')"++log "verifying replay claim is rejected"+api_request "POST" "$CLAIM_API_PATH" "$CLAIM_PAYLOAD"+if [[ "$RESPONSE_CODE" == "201" ]]; then+ fail "claim secret replay unexpectedly succeeded"+fi++log "verifying stored Hermes gateway agent config"+api_request "GET" "/agents/${CREATED_AGENT_ID}"+assert_status "200"++AGENT_ADAPTER_TYPE="$(jq -r '.adapterType // empty' <<<"$RESPONSE_BODY")"+[[ "$AGENT_ADAPTER_TYPE" == "hermes_gateway" ]] || fail "expected adapterType=hermes_gateway, got ${AGENT_ADAPTER_TYPE}"++STORED_API_BASE_URL="$(jq -r '.adapterConfig.apiBaseUrl // empty' <<<"$RESPONSE_BODY")"+[[ -n "$STORED_API_BASE_URL" ]] || fail "stored adapterConfig.apiBaseUrl is missing"+if [[ "$(strip_trailing_slash "$STORED_API_BASE_URL")" != "$(strip_trailing_slash "$HERMES_GATEWAY_API_BASE_URL")" ]]; then+ fail "stored apiBaseUrl mismatch: expected $(strip_trailing_slash "$HERMES_GATEWAY_API_BASE_URL"), got $(strip_trailing_slash "$STORED_API_BASE_URL")"+fi++if jq -e --arg raw "$HERMES_GATEWAY_API_KEY" '.adapterConfig.apiKey == $raw' <<<"$RESPONSE_BODY" >/dev/null; then+ fail "stored adapterConfig.apiKey leaked the raw Hermes API key"+fi+if ! jq -e '(.adapterConfig.apiKey.type // "") == "secret_ref"' <<<"$RESPONSE_BODY" >/dev/null; then+ warn "stored adapterConfig.apiKey is not a visible secret_ref; response shape may redact it entirely"+fi++STORED_SESSION_STRATEGY="$(jq -r '.adapterConfig.sessionKeyStrategy // empty' <<<"$RESPONSE_BODY")"+[[ "$STORED_SESSION_STRATEGY" == "$HERMES_GATEWAY_SESSION_KEY_STRATEGY" ]] || fail "stored sessionKeyStrategy mismatch: expected ${HERMES_GATEWAY_SESSION_KEY_STRATEGY}, got ${STORED_SESSION_STRATEGY:-<empty>}"++if [[ -n "$PAPERCLIP_API_URL_FOR_HERMES" ]]; then+ STORED_PAPERCLIP_API_URL="$(jq -r '.adapterConfig.paperclipApiUrl // empty' <<<"$RESPONSE_BODY")"+ [[ "$STORED_PAPERCLIP_API_URL" == "$PAPERCLIP_API_URL_FOR_HERMES" || "$(strip_trailing_slash "$STORED_PAPERCLIP_API_URL")" == "$(strip_trailing_slash "$PAPERCLIP_API_URL_FOR_HERMES")" ]] \+ || fail "stored paperclipApiUrl mismatch"+fi++log "success"+log "companyId=${COMPANY_ID}"+log "inviteId=${INVITE_ID}"+log "joinRequestId=${JOIN_REQUEST_ID}"+log "agentId=${CREATED_AGENT_ID}"+log "keyId=${KEY_ID}"+log "hermesGatewayApiKeySha256=$(hash_prefix "$HERMES_GATEWAY_API_KEY") len=${#HERMES_GATEWAY_API_KEY}"+log "agentApiKeySha256=$(hash_prefix "$AGENT_API_KEY") len=${#AGENT_API_KEY}"++if [[ -n "$HERMES_JOIN_OUTPUT_FILE" ]]; then+ mkdir -p "$(dirname "$HERMES_JOIN_OUTPUT_FILE")"+ jq -nc \+ --arg companyId "$COMPANY_ID" \+ --arg inviteId "$INVITE_ID" \+ --arg joinRequestId "$JOIN_REQUEST_ID" \+ --arg agentId "$CREATED_AGENT_ID" \+ --arg keyId "$KEY_ID" \+ --arg agentApiKey "$AGENT_API_KEY" \+ --arg hermesGatewayApiKeySha256 "$(hash_prefix "$HERMES_GATEWAY_API_KEY")" \+ --arg agentApiKeySha256 "$(hash_prefix "$AGENT_API_KEY")" \+ '{+ companyId: $companyId,+ inviteId: $inviteId,+ joinRequestId: $joinRequestId,+ agentId: $agentId,+ keyId: $keyId,+ agentApiKey: $agentApiKey,+ hermesGatewayApiKeySha256: $hermesGatewayApiKeySha256,+ agentApiKeySha256: $agentApiKeySha256+ }' > "$HERMES_JOIN_OUTPUT_FILE"+ chmod 600 "$HERMES_JOIN_OUTPUT_FILE"+ log "wrote join metadata to ${HERMES_JOIN_OUTPUT_FILE} (contains secret material; chmod 600)"+fidiff --git a/scripts/smoke/hermes-gateway-smoke.test.mjs b/scripts/smoke/hermes-gateway-smoke.test.mjsnew file mode 100644index 0000000000..49efa5d682--- /dev/null+++ b/scripts/smoke/hermes-gateway-smoke.test.mjs@@ -0,0 +1,155 @@+import assert from "node:assert/strict";+import { spawnSync } from "node:child_process";+import fs from "node:fs";+import path from "node:path";+import { fileURLToPath } from "node:url";+import test from "node:test";++const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");+const joinScript = path.join(repoRoot, "scripts", "smoke", "hermes-gateway-join.sh");+const e2eScript = path.join(repoRoot, "scripts", "smoke", "hermes-gateway-e2e.sh");+const entrypointScript = path.join(repoRoot, "docker", "hermes-gateway-smoke", "entrypoint.sh");++function run(command, args, options = {}) {+ return spawnSync(command, args, {+ cwd: repoRoot,+ encoding: "utf8",+ ...options,+ });+}++function assertSuccess(result, label) {+ assert.equal(+ result.status,+ 0,+ `${label} failed\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,+ );+}++function extractFunction(scriptText, name) {+ const lines = scriptText.split("\n");+ const start = lines.findIndex((line) => line.trim() === `${name}() {`);+ assert.notEqual(start, -1, `missing function ${name}`);++ const collected = [];+ for (let index = start; index < lines.length; index += 1) {+ collected.push(lines[index]);+ if (index > start && lines[index].trim() === "}") {+ return collected.join("\n");+ }+ }+ assert.fail(`unterminated function ${name}`);+}++function runBashFunctions(scriptPath, functionNames, body) {+ const scriptText = fs.readFileSync(scriptPath, "utf8");+ const functions = functionNames.map((name) => extractFunction(scriptText, name)).join("\n\n");+ return run("bash", ["-c", `set -euo pipefail\n${functions}\n${body}`]);+}++test("Hermes gateway smoke shell scripts pass bash syntax validation", () => {+ const result = run("bash", ["-n", joinScript, e2eScript, entrypointScript]);+ assertSuccess(result, "bash -n");+});++test("Hermes gateway smoke help documents operator safety flags", () => {+ for (const script of [joinScript, e2eScript]) {+ const result = run("bash", [script, "--help"]);+ assertSuccess(result, `${path.basename(script)} --help`);+ assert.match(result.stdout, /HERMES_GATEWAY_API_BASE_URL/);+ assert.match(result.stdout, /HERMES_GATEWAY_PROBE_URL/);+ assert.match(result.stdout, /HERMES_GATEWAY_ALLOW_INSECURE_HTTP/);+ assert.match(result.stdout, /redact|redacted|Raw .*keys are redacted/i);+ }++ const e2eHelp = run("bash", [e2eScript, "--help"]).stdout;+ assert.match(e2eHelp, /HERMES_SMOKE_KEEP/);+ assert.match(e2eHelp, /HERMES_SMOKE_NETWORK/);+ assert.match(e2eHelp, /HERMES_SMOKE_MODEL_DEFAULT/);+ assert.match(e2eHelp, /Docker/);+});++test("E2E helper can seed a minimal Hermes model config without secrets", () => {+ const result = runBashFunctions(+ e2eScript,+ ["log", "fail", "yaml_single_quote", "write_hermes_model_config"],+ `+tmp="$(mktemp -d)"+trap 'rm -rf "$tmp"' EXIT+HERMES_SMOKE_STATE_DIR="$tmp"+HERMES_SMOKE_MODEL_PROVIDER="openrouter"+HERMES_SMOKE_MODEL_DEFAULT="z-ai/glm-5.2"+HERMES_SMOKE_MODEL_BASE_URL="https://openrouter.ai/api/v1"+mkdir -p "$HERMES_SMOKE_STATE_DIR/hermes-home"+write_hermes_model_config+config="$HERMES_SMOKE_STATE_DIR/hermes-home/config.yaml"+grep -Fq "default: 'z-ai/glm-5.2'" "$config"+grep -Fq "provider: 'openrouter'" "$config"+grep -Fq "base_url: 'https://openrouter.ai/api/v1'" "$config"+grep -Fq "command_allowlist:" "$config"+grep -Fq -- "- execute_code" "$config"+! grep -Eiq "api[_-]?key|token|secret" "$config"+`,+ );+ assertSuccess(result, "write_hermes_model_config");+});++test("join helper redacts known secrets without exposing raw key material", () => {+ const result = runBashFunctions(+ joinScript,+ ["redact_text"],+ `+HERMES_GATEWAY_API_KEY="gateway-secret"+CLAIM_SECRET="claim-secret"+AGENT_API_KEY="agent-secret"+PAPERCLIP_API_KEY="paperclip-secret"+PAPERCLIP_AUTH_HEADER="Bearer board-secret"+PAPERCLIP_COOKIE="session=board-cookie"+output="$(redact_text "gateway-secret claim-secret agent-secret paperclip-secret Bearer board-secret session=board-cookie")"+[[ "$output" != *"gateway-secret"* ]]+[[ "$output" != *"claim-secret"* ]]+[[ "$output" != *"agent-secret"* ]]+[[ "$output" != *"paperclip-secret"* ]]+[[ "$output" != *"board-secret"* ]]+[[ "$output" != *"board-cookie"* ]]+[[ "$output" == *"[redacted len=14]"* ]]+`,+ );+ assertSuccess(result, "redact_text");+});++test("URL helpers distinguish loopback HTTP from unsafe remote HTTP", () => {+ for (const script of [joinScript, e2eScript]) {+ const result = runBashFunctions(+ script,+ ["url_host", "is_loopback_http_host", "is_remote_plain_http"],+ `+is_remote_plain_http "http://192.168.1.20:8642"+is_remote_plain_http "http://hermes-gateway.local:8642"+is_remote_plain_http "http://127.example.com:8642"+is_remote_plain_http "http://localhost.evil:8642"+! is_remote_plain_http "https://192.168.1.20:8642"+! is_remote_plain_http "http://127.0.0.1:8642"+! is_remote_plain_http "http://127.44.55.66:8642"+! is_remote_plain_http "http://localhost:8642"+! is_remote_plain_http "http://[::1]:8642"+[[ "$(url_host "http://[::1]:8642/health")" == "::1" ]]+[[ "$(url_host "http://127.example.com:8642/health")" == "127.example.com" ]]+`,+ );+ assertSuccess(result, `${path.basename(script)} URL helpers`);+ }+});++test("join helper normalizes trailing slashes for URL comparisons", () => {+ const result = runBashFunctions(+ joinScript,+ ["strip_trailing_slash"],+ `+[[ "$(strip_trailing_slash "http://127.0.0.1:8642///")" == "http://127.0.0.1:8642" ]]+[[ "$(strip_trailing_slash "https://gateway.example.com/")" == "https://gateway.example.com" ]]+[[ "$(strip_trailing_slash "https://gateway.example.com/path/")" == "https://gateway.example.com/path" ]]+`,+ );+ assertSuccess(result, "strip_trailing_slash");+});diff --git a/server/package.json b/server/package.jsonindex 1c9d1cb276..a636d6b544 100644--- a/server/package.json+++ b/server/package.json@@ -59,6 +59,7 @@"@paperclipai/plugin-sdk": "workspace:*","@paperclipai/shared": "workspace:*","@paperclipai/skills-catalog": "workspace:*",+ "@paperclipai/hermes-paperclip-adapter": "workspace:*","ajv": "^8.20.0","ajv-formats": "^3.0.1","better-auth": "1.6.20",@@ -69,7 +70,6 @@"drizzle-orm": "^0.45.2","embedded-postgres": "^18.1.0-beta.16","express": "^5.1.0",- "hermes-paperclip-adapter": "^0.3.0","jsdom": "^28.1.0","multer": "^2.1.1","open": "^11.0.0",diff --git a/server/src/__tests__/adapter-registry.test.ts b/server/src/__tests__/adapter-registry.test.tsindex 983011fe8e..23455f282e 100644--- a/server/src/__tests__/adapter-registry.test.ts+++ b/server/src/__tests__/adapter-registry.test.ts@@ -2,28 +2,6 @@ import { describe, expect, it, beforeEach, afterEach, vi } from "vitest";import { buildSandboxNpmInstallCommand } from "@paperclipai/adapter-utils";import type { ServerAdapterModule } from "../adapters/index.js";-const hermesExecuteMock = vi.hoisted(() =>- vi.fn(async () => ({- exitCode: 0,- signal: null,- timedOut: false,- })),-);--vi.mock("hermes-paperclip-adapter/server", () => ({- execute: hermesExecuteMock,- testEnvironment: async () => ({- adapterType: "hermes_local",- status: "pass",- checks: [],- testedAt: new Date(0).toISOString(),- }),- sessionCodec: null,- listSkills: async () => [],- syncSkills: async () => ({ entries: [] }),- detectModel: async () => null,-}));-import {detectAdapterModel,findActiveServerAdapter,@@ -59,17 +37,18 @@ const externalAdapter: ServerAdapterModule = {describe("server adapter registry", () => {beforeEach(() => {unregisterServerAdapter("external_test");+ unregisterServerAdapter("hermes_local");+ unregisterServerAdapter("hermes_gateway");unregisterServerAdapter("claude_local");setOverridePaused("claude_local", false);- setOverridePaused("hermes_local", true);});afterEach(() => {unregisterServerAdapter("external_test");+ unregisterServerAdapter("hermes_local");+ unregisterServerAdapter("hermes_gateway");unregisterServerAdapter("claude_local");setOverridePaused("claude_local", false);- setOverridePaused("hermes_local", false);- hermesExecuteMock.mockClear();});it("registers external adapters and exposes them through lookup helpers", async () => {@@ -151,6 +130,88 @@ describe("server adapter registry", () => {]);});+ it("ships Hermes adapters as built-ins and still accepts external overrides", () => {+ const builtInLocal = findServerAdapter("hermes_local");+ const builtInGateway = findServerAdapter("hermes_gateway");++ expect(builtInLocal).not.toBeNull();+ expect(builtInLocal?.supportsLocalAgentJwt).toBe(true);+ expect(builtInLocal?.supportsInstructionsBundle).toBe(true);+ expect(builtInLocal?.requiresMaterializedRuntimeSkills).toBe(false);+ expect(builtInLocal?.detectModel).toBeTypeOf("function");+ expect(builtInLocal?.getConfigSchema).toBeTypeOf("function");++ expect(builtInGateway).not.toBeNull();+ expect(builtInGateway?.supportsLocalAgentJwt).toBe(false);+ expect(builtInGateway?.supportsInstructionsBundle).toBe(false);+ expect(builtInGateway?.requiresMaterializedRuntimeSkills).toBe(false);+ expect(builtInGateway?.getConfigSchema).toBeTypeOf("function");++ const hermesLocalExternalAdapter: ServerAdapterModule = {+ type: "hermes_local",+ execute: async () => ({ exitCode: 0, signal: null, timedOut: false }),+ testEnvironment: async () => ({+ adapterType: "hermes_local",+ status: "pass",+ checks: [],+ testedAt: new Date(0).toISOString(),+ }),+ supportsLocalAgentJwt: true,+ supportsInstructionsBundle: true,+ instructionsPathKey: "instructionsFilePath",+ requiresMaterializedRuntimeSkills: false,+ listSkills: async () => ({+ adapterType: "hermes_local",+ supported: true,+ mode: "ephemeral",+ desiredSkills: [],+ entries: [],+ warnings: [],+ }),+ getConfigSchema: () => ({ fields: [{ key: "provider", label: "Provider", type: "text" }] }),+ detectModel: async () => ({+ model: "hermes-model",+ provider: "openrouter",+ source: "test",+ }),+ };++ const hermesGatewayExternalAdapter: ServerAdapterModule = {+ type: "hermes_gateway",+ execute: async () => ({ exitCode: 0, signal: null, timedOut: false }),+ testEnvironment: async () => ({+ adapterType: "hermes_gateway",+ status: "pass",+ checks: [],+ testedAt: new Date(0).toISOString(),+ }),+ supportsLocalAgentJwt: false,+ supportsInstructionsBundle: false,+ requiresMaterializedRuntimeSkills: false,+ getConfigSchema: () => ({+ fields: [{ key: "apiBaseUrl", label: "API URL", type: "text" }],+ }),+ };++ registerServerAdapter(hermesLocalExternalAdapter);++ expect(requireServerAdapter("hermes_local")).toBe(hermesLocalExternalAdapter);+ expect(findActiveServerAdapter("hermes_local")?.supportsLocalAgentJwt).toBe(true);++ unregisterServerAdapter("hermes_local");++ expect(requireServerAdapter("hermes_local")).toBe(builtInLocal);++ registerServerAdapter(hermesGatewayExternalAdapter);++ expect(requireServerAdapter("hermes_gateway")).toBe(hermesGatewayExternalAdapter);+ expect(findActiveServerAdapter("hermes_gateway")?.supportsLocalAgentJwt).toBe(false);++ unregisterServerAdapter("hermes_gateway");++ expect(requireServerAdapter("hermes_gateway")).toBe(builtInGateway);+ });+it("exposes capability flags from registered adapters", () => {const adapterWithCaps: ServerAdapterModule = {type: "external_test",@@ -308,279 +369,6 @@ describe("server adapter registry", () => {expect(await detectAdapterModel("claude_local")).toBeNull();expect(detectModel).toHaveBeenCalledTimes(1);});-- it("injects the local agent JWT and Paperclip API auth guidance into Hermes", async () => {- const adapter = requireServerAdapter("hermes_local");-- await adapter.execute({- runId: "run-123",- agent: {- id: "agent-123",- companyId: "company-123",- name: "Hermes Agent",- role: "engineer",- adapterType: "hermes_local",- adapterConfig: {- env: {- OPENAI_API_KEY: "llm-token",- },- promptTemplate: "Existing prompt",- },- },- runtime: {},- config: {},- context: {},- onLog: async () => {},- onMeta: async () => {},- onSpawn: async () => {},- authToken: "agent-run-jwt",- });-- expect(hermesExecuteMock).toHaveBeenCalledTimes(1);- const [patchedCtx] = hermesExecuteMock.mock.calls[0];- expect(patchedCtx.agent.adapterConfig).toMatchObject({- env: {- OPENAI_API_KEY: "llm-token",- PAPERCLIP_API_KEY: "agent-run-jwt",- PAPERCLIP_RUN_ID: "run-123",- },- });- expect(patchedCtx.agent.adapterConfig.promptTemplate).toContain(- "Authorization: Bearer $PAPERCLIP_API_KEY",- );- expect(patchedCtx.agent.adapterConfig.promptTemplate).toContain(- "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID",- );- expect(patchedCtx.agent.adapterConfig.promptTemplate).toContain("Existing prompt");- });-- it("preserves Hermes command normalization while injecting auth", async () => {- const adapter = requireServerAdapter("hermes_local");-- await adapter.execute({- runId: "run-123",- agent: {- id: "agent-123",- companyId: "company-123",- name: "Hermes Agent",- role: "engineer",- adapterType: "hermes_local",- adapterConfig: {- command: "agent-hermes",- },- },- runtime: {},- config: {- command: "runtime-hermes",- },- context: {},- onLog: async () => {},- onMeta: async () => {},- onSpawn: async () => {},- authToken: "agent-run-jwt",- });-- expect(hermesExecuteMock).toHaveBeenCalledTimes(1);- const [patchedCtx] = hermesExecuteMock.mock.calls[0];- expect(patchedCtx.config.hermesCommand).toBe("runtime-hermes");- expect(patchedCtx.agent.adapterConfig.hermesCommand).toBe("agent-hermes");- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_API_KEY).toBe("agent-run-jwt");- });-- it("passes Hermes custom providers through extraArgs while injecting auth", async () => {- const adapter = requireServerAdapter("hermes_local");-- await adapter.execute({- runId: "run-123",- agent: {- id: "agent-123",- companyId: "company-123",- name: "Hermes Agent",- role: "engineer",- adapterType: "hermes_local",- adapterConfig: {- provider: "custom:paperclip-openai",- extraArgs: ["--source", "tool"],- },- },- runtime: {},- config: {},- context: {},- onLog: async () => {},- onMeta: async () => {},- onSpawn: async () => {},- authToken: "agent-run-jwt",- });-- const [patchedCtx] = hermesExecuteMock.mock.calls[0];- expect(patchedCtx.agent.adapterConfig.provider).toBe("custom:paperclip-openai");- expect(patchedCtx.agent.adapterConfig.extraArgs).toEqual([- "--source",- "tool",- "--provider",- "custom:paperclip-openai",- ]);- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_API_KEY).toBe("agent-run-jwt");- });-- it("does not duplicate an explicit Hermes provider extraArg", async () => {- const adapter = requireServerAdapter("hermes_local");-- await adapter.execute({- runId: "run-123",- agent: {- id: "agent-123",- companyId: "company-123",- name: "Hermes Agent",- role: "engineer",- adapterType: "hermes_local",- adapterConfig: {- provider: "custom:paperclip-openai",- extraArgs: ["--provider=custom:paperclip-openai"],- },- },- runtime: {},- config: {},- context: {},- onLog: async () => {},- onMeta: async () => {},- onSpawn: async () => {},- authToken: "agent-run-jwt",- });-- const [patchedCtx] = hermesExecuteMock.mock.calls[0];- expect(patchedCtx.agent.adapterConfig.extraArgs).toEqual([- "--provider=custom:paperclip-openai",- ]);- });-- it("does not duplicate spaced Hermes provider extraArgs", async () => {- const adapter = requireServerAdapter("hermes_local");-- await adapter.execute({- runId: "run-123",- agent: {- id: "agent-123",- companyId: "company-123",- name: "Hermes Agent",- role: "engineer",- adapterType: "hermes_local",- adapterConfig: {- provider: "custom:paperclip-openai",- extraArgs: ["--provider", "custom:paperclip-openai"],- },- },- runtime: {},- config: {},- context: {},- onLog: async () => {},- onMeta: async () => {},- onSpawn: async () => {},- authToken: "agent-run-jwt",- });-- const [patchedCtx] = hermesExecuteMock.mock.calls[0];- expect(patchedCtx.agent.adapterConfig.extraArgs).toEqual([- "--provider",- "custom:paperclip-openai",- ]);- });-- it("passes the original Hermes context through when authToken is absent", async () => {- const adapter = requireServerAdapter("hermes_local");- const ctx = {- runId: "run-123",- agent: {- id: "agent-123",- companyId: "company-123",- name: "Hermes Agent",- role: "engineer",- adapterType: "hermes_local",- adapterConfig: {- env: {- PAPERCLIP_API_KEY: "server-level-key",- },- promptTemplate: "Existing prompt",- },- },- runtime: {},- config: {},- context: {},- onLog: async () => {},- onMeta: async () => {},- onSpawn: async () => {},- };-- await adapter.execute(ctx);-- expect(hermesExecuteMock).toHaveBeenCalledTimes(1);- expect(hermesExecuteMock).toHaveBeenCalledWith(ctx);- });-- it("preserves an explicit Hermes Paperclip API key and does not set promptTemplate when none was configured", async () => {- const adapter = requireServerAdapter("hermes_local");-- await adapter.execute({- runId: "run-123",- agent: {- id: "agent-123",- companyId: "company-123",- name: "Hermes Agent",- role: "engineer",- adapterType: "hermes_local",- adapterConfig: {- env: {- PAPERCLIP_API_KEY: "explicit-agent-key",- PAPERCLIP_RUN_ID: "stale-run-id",- },- },- },- runtime: {},- config: {},- context: {},- onLog: async () => {},- onMeta: async () => {},- onSpawn: async () => {},- authToken: "agent-run-jwt",- });-- const [patchedCtx] = hermesExecuteMock.mock.calls[0];- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_API_KEY).toBe("explicit-agent-key");- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_RUN_ID).toBe("run-123");- // No custom promptTemplate was set — Hermes must use its built-in default.- // Setting promptTemplate here would replace the full default with just the auth guard text,- // stripping assigned issue / workflow instructions.- expect(patchedCtx.agent.adapterConfig.promptTemplate).toBeUndefined();- });-- it("does not set promptTemplate when no custom template is configured, preserving Hermes default", async () => {- const adapter = requireServerAdapter("hermes_local");-- await adapter.execute({- runId: "run-123",- agent: {- id: "agent-123",- companyId: "company-123",- name: "Hermes Agent",- role: "engineer",- adapterType: "hermes_local",- adapterConfig: {},- },- runtime: {},- config: {},- context: {},- onLog: async () => {},- onMeta: async () => {},- onSpawn: async () => {},- authToken: "agent-run-jwt",- });-- const [patchedCtx] = hermesExecuteMock.mock.calls[0];- // promptTemplate must remain unset so Hermes uses its built-in heartbeat/task prompt.- expect(patchedCtx.agent.adapterConfig.promptTemplate).toBeUndefined();- // Auth token is still injected.- expect(patchedCtx.agent.adapterConfig.env.PAPERCLIP_API_KEY).toBe("agent-run-jwt");- });});describe("resolveExternalAdapterRegistration", () => {diff --git a/server/src/__tests__/adapter-routes.test.ts b/server/src/__tests__/adapter-routes.test.tsindex ccc0edcb5e..13e57a3539 100644--- a/server/src/__tests__/adapter-routes.test.ts+++ b/server/src/__tests__/adapter-routes.test.ts@@ -115,12 +115,14 @@ describe("adapter routes", () => {adapterRoutes = routes.adapterRoutes;errorHandler = middleware.errorHandler;setOverridePaused("claude_local", false);+ unregisterServerAdapter("hermes_local");unregisterServerAdapter("claude_local");registerServerAdapter(overridingConfigSchemaAdapter);});afterEach(() => {setOverridePaused("claude_local", false);+ unregisterServerAdapter("hermes_local");unregisterServerAdapter("claude_local");});@@ -185,17 +187,25 @@ describe("adapter routes", () => {requiresMaterializedRuntimeSkills: true,});- // hermes_local currently supports skills + local JWT, but not the managed- // instructions bundle flow because the bundled adapter does not consume- // instructionsFilePath at runtime.- const hermesAdapter = res.body.find((a: any) => a.type === "hermes_local");- expect(hermesAdapter).toBeDefined();- expect(hermesAdapter.capabilities).toMatchObject({- supportsInstructionsBundle: false,+ const hermesLocal = res.body.find((a: any) => a.type === "hermes_local");+ expect(hermesLocal).toBeDefined();+ expect(hermesLocal.source).toBe("builtin");+ expect(hermesLocal.capabilities).toMatchObject({+ supportsInstructionsBundle: true,supportsSkills: true,supportsLocalAgentJwt: true,requiresMaterializedRuntimeSkills: false,});++ const hermesGateway = res.body.find((a: any) => a.type === "hermes_gateway");+ expect(hermesGateway).toBeDefined();+ expect(hermesGateway.source).toBe("builtin");+ expect(hermesGateway.capabilities).toMatchObject({+ supportsInstructionsBundle: false,+ supportsSkills: false,+ supportsLocalAgentJwt: false,+ requiresMaterializedRuntimeSkills: false,+ });});it("GET /api/adapters derives supportsSkills from listSkills/syncSkills presence", async () => {@@ -277,6 +287,28 @@ describe("adapter routes", () => {expect(keys).not.toContain("bootstrapPromptTemplate");});+ it("serves built-in Hermes config schemas", async () => {+ const app = createApp();++ const local = await request(app).get("/api/adapters/hermes_local/config-schema");+ expect(local.status, JSON.stringify(local.body)).toBe(200);+ expect(local.body.fields).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ key: "provider" }),+ expect.objectContaining({ key: "timeoutSec" }),+ ]),+ );++ const gateway = await request(app).get("/api/adapters/hermes_gateway/config-schema");+ expect(gateway.status, JSON.stringify(gateway.body)).toBe(200);+ expect(gateway.body.fields).toEqual(+ expect.arrayContaining([+ expect.objectContaining({ key: "apiBaseUrl", required: true }),+ expect.objectContaining({ key: "apiKey", required: true }),+ ]),+ );+ });+it("GET /api/adapters includes ACPX model availability", async () => {const app = createApp();diff --git a/server/src/__tests__/agent-permissions-routes.test.ts b/server/src/__tests__/agent-permissions-routes.test.tsindex 70eec87767..9aeda84ac5 100644--- a/server/src/__tests__/agent-permissions-routes.test.ts+++ b/server/src/__tests__/agent-permissions-routes.test.ts@@ -709,7 +709,7 @@ describe.sequential("agent permission routes", () => {model: "gpt-5.3-codex-spark",env: expect.any(Object),}),- { strictMode: false },+ { strictMode: false, adapterType: "codex_local" },);expect(mockAgentService.update).toHaveBeenCalledWith(agentId,diff --git a/server/src/__tests__/agents-service-secret-bindings.test.ts b/server/src/__tests__/agents-service-secret-bindings.test.tsindex 634086cf5b..d27cc58b5c 100644--- a/server/src/__tests__/agents-service-secret-bindings.test.ts+++ b/server/src/__tests__/agents-service-secret-bindings.test.ts@@ -115,6 +115,65 @@ describeEmbeddedPostgres("agent service secret binding sync", () => {});});+ it("converts Hermes gateway apiKey strings into persisted secret refs", async () => {+ const companyId = await seedCompany();+ const literalApiKey = `hermes-key-${randomUUID()}`;++ const created = await agentService(db).create(companyId, {+ name: "Hermes Gateway",+ role: "engineer",+ status: "idle",+ adapterType: "hermes_gateway",+ adapterConfig: {+ apiBaseUrl: "https://hermes.example",+ apiKey: literalApiKey,+ },+ runtimeConfig: {},+ spentMonthlyCents: 0,+ lastHeartbeatAt: null,+ });++ const persistedRows = await db+ .select()+ .from(agents)+ .where(eq(agents.id, created.id));+ const persistedConfig = persistedRows[0]?.adapterConfig as Record<string, unknown>;+ expect(JSON.stringify(persistedConfig)).not.toContain(literalApiKey);+ expect(persistedConfig.apiKey).toMatchObject({+ type: "secret_ref",+ version: "latest",+ });++ const secretId = (persistedConfig.apiKey as { secretId: string }).secretId;+ const bindings = await db+ .select()+ .from(companySecretBindings)+ .where(and(+ eq(companySecretBindings.companyId, companyId),+ eq(companySecretBindings.targetType, "agent"),+ eq(companySecretBindings.targetId, created.id),+ ));+ expect(bindings).toHaveLength(1);+ expect(bindings[0]).toMatchObject({+ secretId,+ configPath: "apiKey",+ versionSelector: "latest",+ required: true,+ });++ const resolved = await secretService(db).resolveAdapterConfigForRuntime(+ companyId,+ persistedConfig,+ {+ consumerType: "agent",+ consumerId: created.id,+ },+ { adapterType: "hermes_gateway" },+ );+ expect(resolved.config.apiKey).toBe(literalApiKey);+ expect(JSON.stringify(persistedConfig)).not.toContain(literalApiKey);+ });+it("replaces agent secret bindings when adapterConfig env changes", async () => {const companyId = await seedCompany();const secrets = secretService(db);diff --git a/server/src/__tests__/authorization-service.test.ts b/server/src/__tests__/authorization-service.test.tsindex 2c1dd29427..aba122f285 100644--- a/server/src/__tests__/authorization-service.test.ts+++ b/server/src/__tests__/authorization-service.test.ts@@ -73,6 +73,8 @@ async function createIssue(projectId?: string | null;parentId?: string | null;assigneeAgentId?: string | null;+ originKind?: string | null;+ originId?: string | null;} = {},) {return db@@ -86,6 +88,8 @@ async function createIssue(projectId: input.projectId ?? null,parentId: input.parentId ?? null,assigneeAgentId: input.assigneeAgentId ?? null,+ originKind: input.originKind ?? "manual",+ originId: input.originId ?? null,}).returning().then((rows) => rows[0]!);@@ -1187,4 +1191,118 @@ describeEmbeddedPostgres("authorization service", () => {grant: { permissionKey: "tasks:assign" },});});++ it("scopes task bridge keys away from company-wide reads and unrelated issue writes", async () => {+ const company = await createCompany(db, "TaskBridge");+ const bridgeAgent = await createAgent(db, company.id);+ const targetAgent = await createAgent(db, company.id);+ const project = await createProject(db, company.id, "Bridge");+ const parentIssue = await createIssue(db, company.id, { projectId: project.id });+ const assignedIssue = await createIssue(db, company.id, { assigneeAgentId: bridgeAgent.id });+ const keyId = randomUUID();+ const bridgeCreatedIssue = await createIssue(db, company.id, {+ originKind: "task_bridge",+ originId: keyId,+ });+ const unrelatedIssue = await createIssue(db, company.id);+ const actor = {+ type: "agent" as const,+ agentId: bridgeAgent.id,+ companyId: company.id,+ source: "agent_key" as const,+ keyId,+ keyScope: {+ kind: "task_bridge" as const,+ parentIssueId: parentIssue.id,+ allowedAssigneeAgentIds: [targetAgent.id],+ },+ };+ const authz = authorizationService(db);++ await expect(authz.decide({+ actor,+ action: "company_scope:read",+ resource: { type: "company", companyId: company.id },+ })).resolves.toMatchObject({+ allowed: false,+ reason: "deny_scope",+ });++ await expect(authz.decide({+ actor,+ action: "tasks:assign",+ resource: {+ type: "issue",+ companyId: company.id,+ parentIssueId: parentIssue.id,+ assigneeAgentId: targetAgent.id,+ },+ })).resolves.toMatchObject({+ allowed: true,+ });++ await expect(authz.decide({+ actor,+ action: "tasks:assign",+ resource: {+ type: "issue",+ companyId: company.id,+ projectId: project.id,+ assigneeUserId: randomUUID(),+ },+ })).resolves.toMatchObject({+ allowed: false,+ reason: "deny_scope",+ });++ await expect(authz.decide({+ actor,+ action: "issue:comment",+ resource: {+ type: "issue",+ companyId: company.id,+ issueId: assignedIssue.id,+ },+ })).resolves.toMatchObject({+ allowed: true,+ });++ await expect(authz.decide({+ actor,+ action: "issue:mutate",+ resource: {+ type: "issue",+ companyId: company.id,+ issueId: bridgeCreatedIssue.id,+ },+ })).resolves.toMatchObject({+ allowed: true,+ });++ await expect(authz.decide({+ actor,+ action: "issue:mutate",+ resource: {+ type: "issue",+ companyId: company.id,+ issueId: unrelatedIssue.id,+ },+ })).resolves.toMatchObject({+ allowed: false,+ reason: "deny_scope",+ });++ await expect(authz.decide({+ actor,+ action: "agent_config:read",+ resource: {+ type: "agent",+ companyId: company.id,+ agentId: bridgeAgent.id,+ },+ })).resolves.toMatchObject({+ allowed: false,+ reason: "deny_scope",+ });+ });});diff --git a/server/src/__tests__/aws-secrets-manager-provider.test.ts b/server/src/__tests__/aws-secrets-manager-provider.test.tsindex 90fec29575..aa006f5e2e 100644--- a/server/src/__tests__/aws-secrets-manager-provider.test.ts+++ b/server/src/__tests__/aws-secrets-manager-provider.test.ts@@ -12,6 +12,11 @@ describe("awsSecretsManagerProvider", () => {AWS_ACCESS_KEY_ID: process.env.AWS_ACCESS_KEY_ID,AWS_SECRET_ACCESS_KEY: process.env.AWS_SECRET_ACCESS_KEY,AWS_SESSION_TOKEN: process.env.AWS_SESSION_TOKEN,+ AWS_PROFILE: process.env.AWS_PROFILE,+ AWS_DEFAULT_PROFILE: process.env.AWS_DEFAULT_PROFILE,+ AWS_CONFIG_FILE: process.env.AWS_CONFIG_FILE,+ AWS_SHARED_CREDENTIALS_FILE: process.env.AWS_SHARED_CREDENTIALS_FILE,+ AWS_SDK_LOAD_CONFIG: process.env.AWS_SDK_LOAD_CONFIG,};afterEach(() => {@@ -169,6 +174,11 @@ describe("awsSecretsManagerProvider", () => {});it("signs AWS Secrets Manager JSON requests with default runtime credentials", async () => {+ delete process.env.AWS_PROFILE;+ delete process.env.AWS_DEFAULT_PROFILE;+ delete process.env.AWS_CONFIG_FILE;+ delete process.env.AWS_SHARED_CREDENTIALS_FILE;+ delete process.env.AWS_SDK_LOAD_CONFIG;process.env.AWS_ACCESS_KEY_ID = "AKIA_TEST_ACCESS";process.env.AWS_SECRET_ACCESS_KEY = "test-secret-key";process.env.AWS_SESSION_TOKEN = "test-session-token";diff --git a/server/src/__tests__/company-portability.test.ts b/server/src/__tests__/company-portability.test.tsindex 8d58ea264f..f4283a0910 100644--- a/server/src/__tests__/company-portability.test.ts+++ b/server/src/__tests__/company-portability.test.ts@@ -1537,7 +1537,7 @@ describe("company portability", () => {},},}),- { strictMode: false },+ { strictMode: false, adapterType: "codex_local" },);expect(agentSvc.create).toHaveBeenCalledWith("company-1", expect.objectContaining({adapterConfig: expect.objectContaining({@@ -3490,7 +3490,7 @@ describe("company portability", () => {expect(secretSvc.normalizeAdapterConfigForPersistence).toHaveBeenCalledWith("company-imported",expect.anything(),- { strictMode: false },+ { strictMode: false, adapterType: "claude_local" },);expect(agentSvc.create).toHaveBeenCalledWith("company-imported", expect.objectContaining({adapterType: "claude_local",@@ -3559,7 +3559,7 @@ describe("company portability", () => {model: "gpt-5.4",extraArgs: ["--skip-git-repo-check"],}),- { strictMode: false },+ { strictMode: false, adapterType: "codex_local" },);expect(agentSvc.update).toHaveBeenCalledWith("agent-1", expect.objectContaining({adapterType: "codex_local",diff --git a/server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts b/server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.tsindex fcde58f3e9..0b99064dc1 100644--- a/server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts+++ b/server/src/__tests__/heartbeat-accepted-plan-workspace-refresh.test.ts@@ -54,6 +54,11 @@ vi.mock("../adapters/index.js", () => ({execute: adapterExecute,supportsLocalAgentJwt: false,}),+ findActiveServerAdapter: () => ({+ type: "codex_local",+ execute: adapterExecute,+ supportsLocalAgentJwt: false,+ }),listAdapterModelProfiles: async () => [],runningProcesses: new Map(),}));diff --git a/server/src/__tests__/heartbeat-plugin-environment.test.ts b/server/src/__tests__/heartbeat-plugin-environment.test.tsindex deda0e9d61..ee7155bb78 100644--- a/server/src/__tests__/heartbeat-plugin-environment.test.ts+++ b/server/src/__tests__/heartbeat-plugin-environment.test.ts@@ -38,6 +38,11 @@ vi.mock("../adapters/index.js", () => ({execute: adapterExecute,supportsLocalAgentJwt: false,}),+ findActiveServerAdapter: () => ({+ type: "codex_local",+ execute: adapterExecute,+ supportsLocalAgentJwt: false,+ }),listAdapterModelProfiles: async () => [],runningProcesses: new Map(),}));diff --git a/server/src/__tests__/invite-accept-gateway-defaults.test.ts b/server/src/__tests__/invite-accept-gateway-defaults.test.tsindex 3ff239f628..cec0f913b6 100644--- a/server/src/__tests__/invite-accept-gateway-defaults.test.ts+++ b/server/src/__tests__/invite-accept-gateway-defaults.test.ts@@ -1,8 +1,36 @@-import { describe, expect, it } from "vitest";+import { randomUUID } from "node:crypto";+import { mkdirSync, rmSync } from "node:fs";+import os from "node:os";+import path from "node:path";+import { afterAll, afterEach, beforeAll, describe, expect, it } from "vitest";+import { eq } from "drizzle-orm";+import {+ companies,+ companySecretProviderConfigs,+ companySecretVersions,+ companySecrets,+ createDb,+ invites,+ joinRequests,+} from "@paperclipai/db";import {buildJoinDefaultsPayloadForAccept,normalizeAgentDefaultsForJoin,+ prepareAgentDefaultsPayloadForJoinPersistence,} from "../routes/access.js";+import {+ getEmbeddedPostgresTestSupport,+ startEmbeddedPostgresTestDatabase,+} from "./helpers/embedded-postgres.js";++const embeddedPostgresSupport = await getEmbeddedPostgresTestSupport();+const describeEmbeddedPostgres = embeddedPostgresSupport.supported ? describe : describe.skip;++if (!embeddedPostgresSupport.supported) {+ console.warn(+ `Skipping embedded Postgres invite accept gateway defaults tests on this host: ${embeddedPostgresSupport.reason ?? "unsupported environment"}`,+ );+}describe("buildJoinDefaultsPayloadForAccept (openclaw_gateway)", () => {it("leaves non-gateway payloads unchanged", () => {@@ -117,3 +145,162 @@ describe("normalizeAgentDefaultsForJoin (openclaw_gateway)", () => {expect(normalized.normalized?.devicePrivateKeyPem).toBeUndefined();});});++describe("normalizeAgentDefaultsForJoin (hermes_gateway)", () => {+ it("rejects remote plain HTTP by default", () => {+ const normalized = normalizeAgentDefaultsForJoin({+ adapterType: "hermes_gateway",+ defaultsPayload: {+ apiBaseUrl: "http://192.168.1.25:8642",+ apiKey: "hermes-key-1234567890",+ },+ deploymentMode: "authenticated",+ deploymentExposure: "private",+ bindHost: "127.0.0.1",+ allowedHostnames: [],+ });++ expect(normalized.fatalErrors.join("\n")).toContain("remote plain HTTP");+ expect(normalized.diagnostics).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ code: "hermes_gateway_plain_http_remote_denied",+ }),+ ]),+ );+ });++ it("allows remote plain HTTP only with the explicit unsafe flag", () => {+ const normalized = normalizeAgentDefaultsForJoin({+ adapterType: "hermes_gateway",+ defaultsPayload: {+ apiBaseUrl: "http://192.168.1.25:8642",+ apiKey: "hermes-key-1234567890",+ dangerouslyAllowInsecureRemoteHttp: true,+ },+ deploymentMode: "authenticated",+ deploymentExposure: "private",+ bindHost: "127.0.0.1",+ allowedHostnames: [],+ });++ expect(normalized.fatalErrors).toEqual([]);+ expect(normalized.normalized?.apiBaseUrl).toBe("http://192.168.1.25:8642/");+ expect(normalized.diagnostics).toEqual(+ expect.arrayContaining([+ expect.objectContaining({+ code: "hermes_gateway_plain_http_remote_unsafe_allowed",+ }),+ ]),+ );+ });+});++describeEmbeddedPostgres("prepareAgentDefaultsPayloadForJoinPersistence (hermes_gateway)", () => {+ let stopDb: (() => Promise<void>) | null = null;+ let db!: ReturnType<typeof createDb>;+ const previousKeyFile = process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;+ const secretsTmpDir = path.join(os.tmpdir(), `paperclip-hermes-join-defaults-${randomUUID()}`);++ beforeAll(async () => {+ mkdirSync(secretsTmpDir, { recursive: true });+ process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE = path.join(secretsTmpDir, "master.key");+ const started = await startEmbeddedPostgresTestDatabase("hermes-join-defaults");+ stopDb = started.cleanup;+ db = createDb(started.connectionString);+ }, 20_000);++ afterEach(async () => {+ await db.delete(joinRequests);+ await db.delete(invites);+ await db.delete(companySecretVersions);+ await db.delete(companySecrets);+ await db.delete(companySecretProviderConfigs);+ await db.delete(companies);+ });++ afterAll(async () => {+ await stopDb?.();+ if (previousKeyFile === undefined) {+ delete process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE;+ } else {+ process.env.PAPERCLIP_SECRETS_MASTER_KEY_FILE = previousKeyFile;+ }+ rmSync(secretsTmpDir, { recursive: true, force: true });+ });++ it("stores a secret ref instead of the literal apiKey in join request defaults", async () => {+ const companyId = randomUUID();+ const inviteId = randomUUID();+ const joinRequestId = randomUUID();+ const literalApiKey = `hermes-key-${randomUUID()}`;++ await db.insert(companies).values({+ id: companyId,+ name: "Paperclip",+ issuePrefix: `T${companyId.replace(/-/g, "").slice(0, 6).toUpperCase()}`,+ requireBoardApprovalForNewAgents: false,+ });+ await db.insert(invites).values({+ id: inviteId,+ companyId,+ inviteType: "company_join",+ tokenHash: `invite-token-${randomUUID()}`,+ allowedJoinTypes: "agent",+ defaultsPayload: null,+ expiresAt: new Date("2027-03-10T00:00:00.000Z"),+ });++ const joinDefaults = normalizeAgentDefaultsForJoin({+ adapterType: "hermes_gateway",+ defaultsPayload: {+ apiBaseUrl: "https://hermes.example",+ apiKey: literalApiKey,+ paperclipApiUrl: "https://paperclip.example",+ },+ deploymentMode: "authenticated",+ deploymentExposure: "private",+ bindHost: "127.0.0.1",+ allowedHostnames: [],+ });+ expect(joinDefaults.fatalErrors).toEqual([]);++ const persistedDefaults = await prepareAgentDefaultsPayloadForJoinPersistence({+ db,+ companyId,+ adapterType: "hermes_gateway",+ normalized: joinDefaults.normalized,+ });++ await db.insert(joinRequests).values({+ id: joinRequestId,+ inviteId,+ companyId,+ requestType: "agent",+ status: "pending_approval",+ requestIp: "127.0.0.1",+ agentName: "Hermes Gateway",+ adapterType: "hermes_gateway",+ capabilities: "Hermes gateway agent",+ agentDefaultsPayload: persistedDefaults,+ claimSecretHash: "claim-secret-hash",+ claimSecretExpiresAt: new Date("2027-03-11T00:00:00.000Z"),+ });++ const persistedJoinRequest = await db+ .select()+ .from(joinRequests)+ .where(eq(joinRequests.id, joinRequestId))+ .then((rows) => rows[0]);+ const storedPayload = persistedJoinRequest?.agentDefaultsPayload as Record<string, unknown>;+ expect(JSON.stringify(storedPayload)).not.toContain(literalApiKey);+ expect(storedPayload.apiKey).toMatchObject({+ type: "secret_ref",+ version: "latest",+ });++ const storedSecrets = await db.select().from(companySecrets);+ expect(storedSecrets).toHaveLength(1);+ expect((storedPayload.apiKey as { secretId: string }).secretId).toBe(storedSecrets[0]?.id);+ });+});diff --git a/server/src/__tests__/invite-onboarding-text.test.ts b/server/src/__tests__/invite-onboarding-text.test.tsindex 7d8407b608..e08828a907 100644--- a/server/src/__tests__/invite-onboarding-text.test.ts+++ b/server/src/__tests__/invite-onboarding-text.test.ts@@ -51,6 +51,21 @@ describe("buildInviteOnboardingTextDocument", () => {expect(text).toContain('"adapterType": "openclaw_gateway"');expect(text).toContain("headers.x-openclaw-token");expect(text).toContain("Do NOT use /v1/responses or /hooks/*");+ expect(text).toContain('adapterType: "hermes_gateway"');+ expect(text).toContain('"adapterType": "hermes_gateway"');+ expect(text).toContain("API_SERVER_ENABLED=true");+ expect(text).toContain("API_SERVER_KEY");+ expect(text).toContain("hermes gateway run --replace --accept-hooks");+ expect(text).toContain("Default Hermes API server port: 8642");+ expect(text).toContain("agentDefaultsPayload.apiBaseUrl");+ expect(text).toContain("agentDefaultsPayload.paperclipApiUrl");+ expect(text).toContain("hermes_local");+ expect(text).toContain("Hermes-originated Paperclip API usage");+ expect(text).toContain("http://127.0.0.1:8642");+ expect(text).toContain("http://192.168.1.25:8642");+ expect(text).toContain("tailnet-name.ts.net:8642");+ expect(text).toContain("http://host.docker.internal:8642");+ expect(text).toContain("https://hermes-gateway.example");expect(text).toContain("set the first reachable candidate as agentDefaultsPayload.paperclipApiUrl");expect(text).toContain("PAPERCLIP_API_KEY");expect(text).toContain("Use your runtime's normal skill or instruction installation path.");diff --git a/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts b/server/src/__tests__/issue-agent-mutation-ownership-routes.test.tsindex f2aabc93e4..e810f3085a 100644--- a/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts+++ b/server/src/__tests__/issue-agent-mutation-ownership-routes.test.ts@@ -669,6 +669,22 @@ describe("agent issue mutation checkout ownership", () => {mockStorageService.deleteObject.mockResolvedValue(undefined);});+ it("denies company-wide issue list routes for task bridge keys", async () => {+ const app = await createApp(peerActor({+ keyId: "99999999-9999-4999-8999-999999999999",+ keyScope: {+ kind: "task_bridge",+ parentIssueId: issueId,+ },+ }));++ const res = await request(app).get(`/api/companies/${companyId}/issues`);++ expect(res.status).toBe(403);+ expect(res.body.error).toContain("Task bridge keys cannot use company-wide issue list APIs");+ expect(mockIssueService.list).not.toHaveBeenCalled();+ });+it("uses the company-scope fast path on the issue list route", async () => {mockAccessService.decide.mockImplementation(async (input: { action: string }) => {if (input.action === "company_scope:read") {diff --git a/server/src/__tests__/llms-routes.test.ts b/server/src/__tests__/llms-routes.test.tsindex fa530d9292..6078d98893 100644--- a/server/src/__tests__/llms-routes.test.ts+++ b/server/src/__tests__/llms-routes.test.ts@@ -72,4 +72,39 @@ describe("llm routes", () => {expect(res.text).toContain("Timer heartbeats are opt-in for new hires.");expect(res.text).toContain("Leave runtimeConfig.heartbeat.enabled false");});++ it("serves static Hermes Gateway configuration docs before the plugin is installed", async () => {+ const app = await createApp({+ type: "board",+ userId: "board-user",+ companyIds: ["company-1"],+ source: "local_implicit",+ isInstanceAdmin: true,+ });++ const indexRes = await request(app).get("/api/llms/agent-configuration.txt");+ expect(indexRes.status).toBe(200);+ expect(indexRes.text).toContain(+ "- hermes_gateway: /llms/agent-configuration/hermes_gateway.txt",+ );++ const res = await request(app).get("/api/llms/agent-configuration/hermes_gateway.txt");++ expect(res.status).toBe(200);+ expect(res.text).toContain("Adapter: hermes_gateway");+ expect(res.text).toContain('adapterType": "hermes_gateway"');+ expect(res.text).toContain("API_SERVER_ENABLED=true");+ expect(res.text).toContain("API_SERVER_KEY");+ expect(res.text).toContain("hermes gateway run --replace --accept-hooks");+ expect(res.text).toContain("Default Hermes API server port: 8642");+ expect(res.text).toContain("agentDefaultsPayload.apiBaseUrl");+ expect(res.text).toContain("agentDefaultsPayload.paperclipApiUrl");+ expect(res.text).toContain("hermes_local");+ expect(res.text).toContain("Hermes-originated Paperclip API usage");+ expect(res.text).toContain("http://127.0.0.1:8642");+ expect(res.text).toContain("http://192.168.1.25:8642");+ expect(res.text).toContain("tailnet-name.ts.net:8642");+ expect(res.text).toContain("http://host.docker.internal:8642");+ expect(res.text).toContain("https://hermes-gateway.example");+ });});diff --git a/server/src/__tests__/secrets-service.test.ts b/server/src/__tests__/secrets-service.test.tsindex 3bc48eb908..eda8c2f953 100644--- a/server/src/__tests__/secrets-service.test.ts+++ b/server/src/__tests__/secrets-service.test.ts@@ -998,6 +998,11 @@ describeEmbeddedPostgres("secretService", () => {version: 1,},}));++ const persisted = await svc.getByName(companyId, "Create Rollback");+ expect(persisted).toBeNull();+ const versions = await db.select().from(companySecretVersions);+ expect(versions).toHaveLength(0);});it("keeps a local cleanup handle when create rollback cleanup fails", async () => {diff --git a/server/src/adapters/builtin-adapter-types.ts b/server/src/adapters/builtin-adapter-types.tsindex bb96eb9962..505162f7ed 100644--- a/server/src/adapters/builtin-adapter-types.ts+++ b/server/src/adapters/builtin-adapter-types.ts@@ -9,10 +9,11 @@ export const BUILTIN_ADAPTER_TYPES = new Set(["cursor","gemini_local","grok_local",+ "hermes_gateway",+ "hermes_local","openclaw_gateway","opencode_local","pi_local",- "hermes_local","process","http",]);diff --git a/server/src/adapters/hermes-gateway-doc.ts b/server/src/adapters/hermes-gateway-doc.tsnew file mode 100644index 0000000000..8fc2716806--- /dev/null+++ b/server/src/adapters/hermes-gateway-doc.ts@@ -0,0 +1,56 @@+export const hermesGatewayAgentConfigurationDoc = `# hermes_gateway agent configuration++Adapter: hermes_gateway++Use when:+- Hermes is already running outside Paperclip and exposes its API server.+- Paperclip should invoke Hermes through the gateway HTTP API instead of spawning Hermes locally.+- The Hermes runtime may live on another host, a private overlay, in Docker, or behind a TLS reverse proxy.++Don't use when:+- Paperclip should start the Hermes CLI directly on the same host. Use the built-in hermes_local adapter for that flow.+- Hermes is the process calling Paperclip APIs after claiming its key. That is Hermes-originated Paperclip API usage, not the gateway adapter transport.++Runtime distinction:+- hermes_local: Paperclip starts Hermes on the Paperclip host through the built-in local adapter.+- hermes_gateway: Paperclip calls an already-running Hermes API server using agentDefaultsPayload.apiBaseUrl.+- Hermes-originated Paperclip API usage: Hermes calls Paperclip with PAPERCLIP_API_URL and PAPERCLIP_BRIDGE_API_KEY. Create that Paperclip key with scope.kind = "task_bridge" and an approved parent/project boundary; do not expose a normal claimed agent key to Hermes-facing chat/webhook surfaces. Do not use agentDefaultsPayload.apiBaseUrl for Paperclip API calls.++Hermes gateway process setup:+- Set API_SERVER_ENABLED=true.+- Set API_SERVER_KEY to a generated secret value. Do not paste a real key into tickets, docs, screenshots, or tests.+- Start Hermes with: hermes gateway run --replace --accept-hooks+- Default Hermes API server port: 8642.++Join request minimum:+{+ "requestType": "agent",+ "agentName": "My Hermes Gateway Agent",+ "adapterType": "hermes_gateway",+ "capabilities": "Hermes gateway agent",+ "agentDefaultsPayload": {+ "apiBaseUrl": "http://127.0.0.1:8642",+ "apiKey": "<same-value-as-API_SERVER_KEY>",+ "paperclipApiUrl": "http://localhost:3100"+ }+}++Core fields:+- agentDefaultsPayload.apiBaseUrl (string, required): Base URL for the Hermes API server as reachable from the Paperclip server.+- agentDefaultsPayload.apiKey (string, required unless the adapter package documents another auth field): Hermes API server key matching API_SERVER_KEY.+- agentDefaultsPayload.paperclipApiUrl (string, strongly recommended): Paperclip base URL as reachable from Hermes for invite, claim, skill bootstrap, and later Paperclip API calls.+- agentDefaultsPayload.timeoutSec or timeoutMs (number, optional): Runtime request timeout when supported by the installed Hermes gateway adapter.++Network examples:+- Local loopback on one host: agentDefaultsPayload.apiBaseUrl = "http://127.0.0.1:8642"; agentDefaultsPayload.paperclipApiUrl = "http://127.0.0.1:3100".+- LAN/private network: agentDefaultsPayload.apiBaseUrl = "http://192.168.1.25:8642"; agentDefaultsPayload.paperclipApiUrl = "http://192.168.1.10:3100". Use private IPs or hostnames reachable from both machines.+- Private overlay: agentDefaultsPayload.apiBaseUrl = "http://hermes-host.tailnet-name.ts.net:8642"; agentDefaultsPayload.paperclipApiUrl = "http://paperclip-host.tailnet-name.ts.net:3100". Add the Paperclip hostname with pnpm paperclipai allowed-hostname <host> when authenticated/private mode requires it.+- Docker: if Hermes runs on the host and Paperclip runs in Docker, use agentDefaultsPayload.apiBaseUrl = "http://host.docker.internal:8642". If Hermes runs in another container, use the Compose service DNS name such as "http://hermes:8642".+- Reverse proxy/TLS: publish Hermes behind HTTPS and set agentDefaultsPayload.apiBaseUrl = "https://hermes-gateway.example"; set agentDefaultsPayload.paperclipApiUrl = "https://paperclip.example". Keep API_SERVER_KEY required at the origin or proxy.++Security notes:+- Treat API_SERVER_KEY and PAPERCLIP_BRIDGE_API_KEY as secrets.+- Never use a normal claimed Paperclip agent API key for internet-facing Hermes-originated task bridge calls; task_bridge keys cannot use company-wide issue list/search/read surfaces and can only mutate bridge-created or assigned issues.+- Prefer private network or TLS for non-loopback gateway access.+- Use placeholders such as <same-value-as-API_SERVER_KEY> in docs and tests.+`;diff --git a/server/src/adapters/registry.ts b/server/src/adapters/registry.tsindex 315f02dd74..c60d91948a 100644--- a/server/src/adapters/registry.ts+++ b/server/src/adapters/registry.ts@@ -92,6 +92,10 @@ import {agentConfigurationDoc as grokAgentConfigurationDoc,models as grokModels,} from "@paperclipai/adapter-grok-local";+import {+ createHermesGatewayServerAdapter,+ createHermesLocalServerAdapter,+} from "@paperclipai/hermes-paperclip-adapter";import {execute as openCodeExecute,listOpenCodeSkills,@@ -127,18 +131,6 @@ import {agentConfigurationDoc as piAgentConfigurationDoc,modelProfiles as piModelProfiles,} from "@paperclipai/adapter-pi-local";-import {- execute as hermesExecute,- testEnvironment as hermesTestEnvironment,- sessionCodec as hermesSessionCodec,- listSkills as hermesListSkills,- syncSkills as hermesSyncSkills,- detectModel as detectModelFromHermes,-} from "hermes-paperclip-adapter/server";-import {- agentConfigurationDoc as hermesAgentConfigurationDoc,- models as hermesModels,-} from "hermes-paperclip-adapter";import { BUILTIN_ADAPTER_TYPES } from "./builtin-adapter-types.js";import { buildExternalAdapters } from "./plugin-loader.js";import { getDisabledAdapterTypes } from "../services/adapter-plugin-store.js";@@ -184,55 +176,6 @@ function buildCursorRuntimeCommandSpec(config: Record<string, unknown>): Adapter};}-function normalizeHermesConfig<T extends { config?: unknown; agent?: unknown }>(ctx: T): T {- const config =- ctx && typeof ctx === "object" && "config" in ctx && ctx.config && typeof ctx.config === "object"- ? (ctx.config as Record<string, unknown>)- : null;- const agent =- ctx && typeof ctx === "object" && "agent" in ctx && ctx.agent && typeof ctx.agent === "object"- ? (ctx.agent as Record<string, unknown>)- : null;- const agentAdapterConfig =- agent?.adapterConfig && typeof agent.adapterConfig === "object"- ? (agent.adapterConfig as Record<string, unknown>)- : null;-- const configCommand =- typeof config?.command === "string" && config.command.length > 0 ? config.command : undefined;- const agentCommand =- typeof agentAdapterConfig?.command === "string" && agentAdapterConfig.command.length > 0- ? agentAdapterConfig.command- : undefined;-- if (config && !config.hermesCommand && configCommand) {- config.hermesCommand = configCommand;- }- if (agentAdapterConfig && !agentAdapterConfig.hermesCommand && agentCommand) {- agentAdapterConfig.hermesCommand = agentCommand;- }-- return ctx;-}--function passHermesCustomProviderThroughExtraArgs(config: Record<string, unknown>): Record<string, unknown> {- const provider = typeof config.provider === "string" ? config.provider.trim() : "";- if (!provider.startsWith("custom:")) return config;-- const existingExtraArgs = Array.isArray(config.extraArgs)- ? config.extraArgs.filter((arg): arg is string => typeof arg === "string")- : [];- const alreadyHasProviderArg = existingExtraArgs.some((arg) =>- arg === "--provider" || arg.startsWith("--provider=")- );- if (alreadyHasProviderArg) return config;-- return {- ...config,- extraArgs: [...existingExtraArgs, "--provider", provider],- };-}-function dedupeAdapterModels(models: AdapterModel[]): AdapterModel[] {const seen = new Set<string>();const result: AdapterModel[] = [];@@ -403,6 +346,10 @@ const grokLocalAdapter: ServerAdapterModule = {agentConfigurationDoc: grokAgentConfigurationDoc,};+const hermesGatewayAdapter = createHermesGatewayServerAdapter();++const hermesLocalAdapter = createHermesLocalServerAdapter();+const openclawGatewayAdapter: ServerAdapterModule = {type: "openclaw_gateway",execute: openclawGatewayExecute,@@ -453,77 +400,6 @@ const piLocalAdapter: ServerAdapterModule = {agentConfigurationDoc: piAgentConfigurationDoc,};-// hermes-paperclip-adapter v0.2.0 predates the authToken field; cast is-// intentional until hermes ships a matching AdapterExecutionContext type.-const executeHermesLocal = hermesExecute as unknown as ServerAdapterModule["execute"];-// hermes-paperclip-adapter v0.2.0 still depends on the published @paperclipai/adapter-utils-// that ships the "paperclip_required" origin; casts bridge until hermes upgrades.-const listHermesSkills = hermesListSkills as unknown as ServerAdapterModule["listSkills"];-const syncHermesSkills = hermesSyncSkills as unknown as ServerAdapterModule["syncSkills"];--const hermesLocalAdapter: ServerAdapterModule = {- type: "hermes_local",- execute: async (ctx) => {- const normalizedCtx = normalizeHermesConfig(ctx);- if (!normalizedCtx.authToken) return executeHermesLocal(normalizedCtx);-- const existingConfig = (normalizedCtx.agent.adapterConfig ?? {}) as Record<string, unknown>;- const existingEnv =- typeof existingConfig.env === "object" && existingConfig.env !== null && !Array.isArray(existingConfig.env)- ? (existingConfig.env as Record<string, string>)- : {};- const explicitApiKey =- typeof existingEnv.PAPERCLIP_API_KEY === "string" && existingEnv.PAPERCLIP_API_KEY.trim().length > 0;- const promptTemplate =- typeof existingConfig.promptTemplate === "string" && existingConfig.promptTemplate.trim().length > 0- ? existingConfig.promptTemplate- : "";- const authGuardPrompt = [- "Paperclip API safety rule:",- "Use Authorization: Bearer $PAPERCLIP_API_KEY on every Paperclip API request.",- "Use X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID on every Paperclip API request that writes or mutates data, including comments and issue updates.",- "Never use a board, browser, or local-board session for Paperclip API writes.",- ].join("\n");-- const patchedConfig: Record<string, unknown> = {- ...existingConfig,- env: {- ...existingEnv,- ...(!explicitApiKey ? { PAPERCLIP_API_KEY: normalizedCtx.authToken } : {}),- PAPERCLIP_RUN_ID: normalizedCtx.runId,- },- };- const effectivePatchedConfig = passHermesCustomProviderThroughExtraArgs(patchedConfig);-- // Only inject the auth guard into promptTemplate when a custom template already exists.- // When no custom template is set, Hermes uses its built-in default heartbeat/task prompt —- // overwriting it with only the auth guard text would strip the assigned issue/workflow instructions.- if (promptTemplate) {- effectivePatchedConfig.promptTemplate = `${authGuardPrompt}\n\n${promptTemplate}`;- }-- const patchedCtx = {- ...normalizedCtx,- agent: {- ...normalizedCtx.agent,- adapterConfig: effectivePatchedConfig,- },- };-- return executeHermesLocal(patchedCtx);- },- testEnvironment: (ctx) => hermesTestEnvironment(normalizeHermesConfig(ctx) as never),- sessionCodec: hermesSessionCodec,- listSkills: listHermesSkills,- syncSkills: syncHermesSkills,- models: hermesModels,- supportsLocalAgentJwt: true,- supportsInstructionsBundle: false,- requiresMaterializedRuntimeSkills: false,- agentConfigurationDoc: hermesAgentConfigurationDoc,- detectModel: () => detectModelFromHermes(),-};-const adaptersByType = new Map<string, ServerAdapterModule>();// For builtin types that are overridden by an external adapter, we keep the@@ -546,8 +422,9 @@ function registerBuiltInAdapters() {cursorLocalAdapter,geminiLocalAdapter,grokLocalAdapter,- openclawGatewayAdapter,+ hermesGatewayAdapter,hermesLocalAdapter,+ openclawGatewayAdapter,processAdapter,httpAdapter,]) {diff --git a/server/src/middleware/auth.ts b/server/src/middleware/auth.tsindex c0cbf954dd..46650a0beb 100644--- a/server/src/middleware/auth.ts+++ b/server/src/middleware/auth.ts@@ -4,7 +4,7 @@ import { and, eq, isNull } from "drizzle-orm";import type { Db } from "@paperclipai/db";import { agentApiKeys, agents, authUsers, companies, companyMemberships, instanceUserRoles } from "@paperclipai/db";import { verifyLocalAgentJwt } from "../agent-auth-jwt.js";-import type { DeploymentMode } from "@paperclipai/shared";+import { normalizeAgentApiKeyScope, type DeploymentMode } from "@paperclipai/shared";import type { BetterAuthSessionResult } from "../auth/better-auth.js";import { logger } from "./logger.js";import { boardAuthService } from "../services/board-auth.js";@@ -192,6 +192,7 @@ export function actorMiddleware(db: Db, opts: ActorMiddlewareOptions): RequestHaagentId: key.agentId,companyId: key.companyId,keyId: key.id,+ keyScope: normalizeAgentApiKeyScope(key.scopeConfig),runId: runIdHeader || undefined,source: "agent_key",};diff --git a/server/src/routes/access.ts b/server/src/routes/access.tsindex a4a2fea15b..0de06e57c7 100644--- a/server/src/routes/access.ts+++ b/server/src/routes/access.ts@@ -83,6 +83,7 @@ import {} from "../board-claim.js";import { claimFirstInstanceAdmin } from "../first-admin-claim.js";import { getStorageService } from "../storage/index.js";+import { secretService } from "../services/secrets.js";function hashToken(token: string) {return createHash("sha256").update(token).digest("hex");@@ -294,8 +295,14 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {}function isLoopbackHost(hostname: string): boolean {- const value = hostname.trim().toLowerCase();- return value === "localhost" || value === "127.0.0.1" || value === "::1";+ const value = hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");+ return (+ value === "localhost" ||+ value === "::1" ||+ value === "0:0:0:0:0:0:0:1" ||+ value === "127.0.0.1" ||+ /^127(?:\.\d{1,3}){3}$/.test(value)+ );}function normalizeHostname(value: string | null | undefined): string | null {@@ -474,8 +481,8 @@ function parseBooleanLike(value: unknown): boolean | null {if (typeof value === "boolean") return value;if (typeof value !== "string") return null;const normalized = value.trim().toLowerCase();- if (normalized === "true" || normalized === "1") return true;- if (normalized === "false" || normalized === "0") return false;+ if (["true", "1", "yes", "on"].includes(normalized)) return true;+ if (["false", "0", "no", "off"].includes(normalized)) return false;return null;}@@ -676,6 +683,91 @@ export function normalizeAgentDefaultsForJoin(input: {}) {const fatalErrors: string[] = [];const diagnostics: JoinDiagnostic[] = [];+ if (input.adapterType === "hermes_gateway") {+ if (!isPlainObject(input.defaultsPayload)) {+ diagnostics.push({+ code: "hermes_gateway_defaults_missing",+ level: "warn",+ message: "No Hermes gateway config was provided in agentDefaultsPayload.",+ hint: "Include agentDefaultsPayload.apiBaseUrl and agentDefaultsPayload.apiKey for Hermes gateway joins.",+ });+ fatalErrors.push("agentDefaultsPayload is required for adapterType=hermes_gateway");+ return { normalized: null as Record<string, unknown> | null, diagnostics, fatalErrors };+ }++ const defaults = input.defaultsPayload as Record<string, unknown>;+ const normalized = { ...defaults };+ const rawApiBaseUrl = nonEmptyTrimmedString(defaults.apiBaseUrl ?? defaults.url);+ if (!rawApiBaseUrl) {+ diagnostics.push({+ code: "hermes_gateway_api_base_url_missing",+ level: "warn",+ message: "Hermes gateway apiBaseUrl is missing.",+ hint: "Set agentDefaultsPayload.apiBaseUrl to the Hermes API server URL.",+ });+ fatalErrors.push("agentDefaultsPayload.apiBaseUrl is required");+ } else {+ try {+ const apiBaseUrl = new URL(rawApiBaseUrl);+ if (apiBaseUrl.protocol !== "http:" && apiBaseUrl.protocol !== "https:") {+ diagnostics.push({+ code: "hermes_gateway_api_base_url_protocol",+ level: "warn",+ message: `Hermes gateway apiBaseUrl must use http:// or https:// (got ${apiBaseUrl.protocol}).`,+ });+ fatalErrors.push("agentDefaultsPayload.apiBaseUrl must use http:// or https:// for hermes_gateway");+ } else if (+ apiBaseUrl.protocol === "http:" &&+ !isLoopbackHost(apiBaseUrl.hostname) &&+ parseBooleanLike(defaults.dangerouslyAllowInsecureRemoteHttp) !== true+ ) {+ diagnostics.push({+ code: "hermes_gateway_plain_http_remote_denied",+ level: "warn",+ message: "Remote plain HTTP Hermes gateway traffic is denied by default.",+ hint: "Use https:// or set agentDefaultsPayload.dangerouslyAllowInsecureRemoteHttp=true only for unsafe local development.",+ });+ fatalErrors.push(+ "agentDefaultsPayload.apiBaseUrl uses remote plain HTTP; use HTTPS or set dangerouslyAllowInsecureRemoteHttp=true for unsafe local development",+ );+ } else {+ normalized.apiBaseUrl = apiBaseUrl.toString();+ if (apiBaseUrl.protocol === "http:" && !isLoopbackHost(apiBaseUrl.hostname)) {+ diagnostics.push({+ code: "hermes_gateway_plain_http_remote_unsafe_allowed",+ level: "warn",+ message: "Unsafe dev escape hatch enabled for non-loopback HTTP Hermes traffic.",+ });+ } else {+ diagnostics.push({+ code: "hermes_gateway_api_base_url_configured",+ level: "info",+ message: `Hermes gateway endpoint set to ${apiBaseUrl.toString()}`,+ });+ }+ }+ } catch {+ diagnostics.push({+ code: "hermes_gateway_api_base_url_invalid",+ level: "warn",+ message: `Invalid Hermes gateway apiBaseUrl: ${rawApiBaseUrl}`,+ });+ fatalErrors.push("agentDefaultsPayload.apiBaseUrl is not a valid URL");+ }+ }++ if (!nonEmptyTrimmedString(defaults.apiKey)) {+ diagnostics.push({+ code: "hermes_gateway_api_key_missing",+ level: "warn",+ message: "Hermes gateway API key is missing.",+ hint: "Set agentDefaultsPayload.apiKey to the Hermes API_SERVER_KEY value.",+ });+ fatalErrors.push("agentDefaultsPayload.apiKey is required");+ }++ return { normalized, diagnostics, fatalErrors };+ }if (input.adapterType !== "openclaw_gateway") {const normalized = isPlainObject(input.defaultsPayload)? (input.defaultsPayload as Record<string, unknown>)@@ -919,6 +1011,24 @@ export function normalizeAgentDefaultsForJoin(input: {return { normalized, diagnostics, fatalErrors };}+export async function prepareAgentDefaultsPayloadForJoinPersistence(input: {+ db: Db;+ companyId: string;+ adapterType: string | null;+ normalized: Record<string, unknown> | null;+ actor?: { userId?: string | null; agentId?: string | null };+}): Promise<Record<string, unknown> | null> {+ if (input.adapterType !== "hermes_gateway" || !input.normalized) {+ return input.normalized;+ }++ return secretService(input.db).normalizeAdapterConfigForPersistence(+ input.companyId,+ input.normalized,+ { adapterType: input.adapterType, actor: input.actor },+ );+}+function toInviteSummaryResponse(req: Request,token: string,@@ -1585,17 +1695,17 @@ function buildInviteOnboardingManifest(),onboarding: {instructions:- "Join as an external Paperclip agent, save your one-time claim secret, wait for board approval, then claim your API key. Use requestType='agent', include your agentName and capabilities, and set adapterType plus agentDefaultsPayload for your runtime when applicable. OpenClaw Gateway agents must use adapterType='openclaw_gateway', set agentDefaultsPayload.url to a ws:// or wss:// gateway endpoint, and include agentDefaultsPayload.headers.x-openclaw-token.",+ "Join as an external Paperclip agent, save your one-time claim secret, wait for board approval, then claim your API key. Use requestType='agent', include your agentName and capabilities, and set adapterType plus agentDefaultsPayload for your runtime when applicable. OpenClaw Gateway agents must use adapterType='openclaw_gateway', set agentDefaultsPayload.url to a ws:// or wss:// gateway endpoint, and include agentDefaultsPayload.headers.x-openclaw-token. Hermes Gateway agents must use adapterType='hermes_gateway', start Hermes with API_SERVER_ENABLED=true, API_SERVER_KEY, and `hermes gateway run --replace --accept-hooks`, then set agentDefaultsPayload.apiBaseUrl and agentDefaultsPayload.paperclipApiUrl.",inviteMessage: extractInviteMessage(invite),recommendedAdapterType: null,requiredFields: {requestType: "agent",agentName: "Display name for this agent",adapterType:- "Adapter type for this runtime. Use 'openclaw_gateway' only for OpenClaw Gateway agents.",+ "Adapter type for this runtime. Use 'openclaw_gateway' only for OpenClaw Gateway agents. Use 'hermes_gateway' only for Hermes Gateway agents.",capabilities: "Optional capability summary",agentDefaultsPayload:- "Runtime-specific adapter config. OpenClaw Gateway agents must include url (ws:// or wss://) and headers.x-openclaw-token. Other runtimes should include the config their adapter expects."+ "Runtime-specific adapter config. OpenClaw Gateway agents must include url (ws:// or wss://) and headers.x-openclaw-token. Hermes Gateway agents must include apiBaseUrl, API_SERVER_KEY-backed auth, and paperclipApiUrl. Other runtimes should include the config their adapter expects."},registrationEndpoint: {method: "POST",@@ -1744,6 +1854,37 @@ export function buildInviteOnboardingTextDocument(For OpenClaw Gateway, include agentDefaultsPayload.headers.x-openclaw-token with your gateway token. Legacy x-openclaw-auth is also accepted, but x-openclaw-token is preferred. Do NOT use /v1/responses or /hooks/* in this gateway join flow.+ Hermes Gateway setup:+ - adapterType: "hermes_gateway"+ - Start Hermes with API_SERVER_ENABLED=true and API_SERVER_KEY=<random-gateway-key>.+ - Run: hermes gateway run --replace --accept-hooks+ - Default Hermes API server port: 8642.+ - Set agentDefaultsPayload.apiBaseUrl to the Hermes gateway URL Paperclip can reach.+ - Set agentDefaultsPayload.paperclipApiUrl to the Paperclip base URL Hermes can reach.+ - Use hermes_local when Paperclip should start Hermes on the Paperclip host.+ - Use hermes_gateway when Paperclip should call an already-running Hermes API server.+ - Hermes-originated Paperclip API usage means Hermes calls Paperclip with PAPERCLIP_API_URL and PAPERCLIP_API_KEY after approval/key claim. Do not confuse that with agentDefaultsPayload.apiBaseUrl, which points Paperclip to Hermes.++ Hermes Gateway payload example:+ {+ "requestType": "agent",+ "agentName": "My Hermes Gateway Agent",+ "adapterType": "hermes_gateway",+ "capabilities": "Hermes gateway agent",+ "agentDefaultsPayload": {+ "apiBaseUrl": "http://127.0.0.1:8642",+ "apiKey": "<same-value-as-API_SERVER_KEY>",+ "paperclipApiUrl": "http://localhost:3100"+ }+ }++ Hermes Gateway network examples:+ - Local loopback: agentDefaultsPayload.apiBaseUrl = "http://127.0.0.1:8642" and agentDefaultsPayload.paperclipApiUrl = "http://127.0.0.1:3100".+ - LAN/private network: use reachable private addresses, for example agentDefaultsPayload.apiBaseUrl = "http://192.168.1.25:8642" and agentDefaultsPayload.paperclipApiUrl = "http://192.168.1.10:3100".+ - Private overlay: use overlay DNS names, for example agentDefaultsPayload.apiBaseUrl = "http://hermes-host.tailnet-name.ts.net:8642" and agentDefaultsPayload.paperclipApiUrl = "http://paperclip-host.tailnet-name.ts.net:3100".+ - Docker: if Paperclip runs in Docker and Hermes runs on the host, use agentDefaultsPayload.apiBaseUrl = "http://host.docker.internal:8642"; if both run in Compose, use the Hermes service name.+ - Reverse proxy/TLS: use HTTPS origins, for example agentDefaultsPayload.apiBaseUrl = "https://hermes-gateway.example" and agentDefaultsPayload.paperclipApiUrl = "https://paperclip.example".+Expected response includes:- request id- one-time claimSecret@@ -3565,6 +3706,20 @@ export function accessRoutes(throw badRequest(joinDefaults.fatalErrors.join("; "));}+ const persistedJoinDefaultsPayload =+ requestType === "agent"+ ? await prepareAgentDefaultsPayloadForJoinPersistence({+ db,+ companyId,+ adapterType,+ normalized: joinDefaults.normalized,+ actor: {+ userId: req.actor.userId ?? null,+ agentId: req.actor.agentId ?? null+ }+ })+ : null;+if (requestType === "agent" && adapterType === "openclaw_gateway") {logger.info({@@ -3658,7 +3813,7 @@ export function accessRoutes(? req.body.capabilities ?? null: null,agentDefaultsPayload:- requestType === "agent" ? joinDefaults.normalized : null,+ requestType === "agent" ? persistedJoinDefaultsPayload : null,claimSecretHash,claimSecretExpiresAt})@@ -3684,7 +3839,7 @@ export function accessRoutes(: null,adapterType: requestType === "agent" ? adapterType : null,agentDefaultsPayload:- requestType === "agent" ? joinDefaults.normalized : null,+ requestType === "agent" ? persistedJoinDefaultsPayload : null,updatedAt: new Date()}).where(eq(joinRequests.id, replayJoinRequestId as string))diff --git a/server/src/routes/agents.ts b/server/src/routes/agents.tsindex 055abfb5c1..57c63ea9ad 100644--- a/server/src/routes/agents.ts+++ b/server/src/routes/agents.ts@@ -140,7 +140,6 @@ export function agentRoutes(codex_local: "instructionsFilePath",droid_local: "instructionsFilePath",gemini_local: "instructionsFilePath",- hermes_local: "instructionsFilePath",opencode_local: "instructionsFilePath",cursor: "instructionsFilePath",pi_local: "instructionsFilePath",@@ -1079,7 +1078,10 @@ export function agentRoutes(const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(input.companyId,input.adapterConfig,- { strictMode: strictSecretsMode },+ {+ strictMode: strictSecretsMode,+ adapterType: input.adapterType ?? null,+ },);await assertAdapterConfigConstraints(input.adapterType,@@ -1617,11 +1619,13 @@ export function agentRoutes(const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(companyId,inputAdapterConfig,- { strictMode: strictSecretsMode },+ { strictMode: strictSecretsMode, adapterType: type },);const { config: runtimeAdapterConfig } = await secretsSvc.resolveAdapterConfigForRuntime(companyId,normalizedAdapterConfig,+ undefined,+ { adapterType: type },);const { executionTarget, environmentName, fallbackChecks, release } =@@ -1943,6 +1947,18 @@ export function agentRoutes(res.json(buildLowTrustSelfView(agent));return;}+ if (req.actor.keyScope?.kind === "task_bridge") {+ res.json({+ id: agent.id,+ companyId: agent.companyId,+ name: agent.name,+ role: agent.role,+ title: agent.title,+ status: agent.status,+ keyScope: req.actor.keyScope,+ });+ return;+ }res.json(await buildAgentDetail(agent));});@@ -2572,7 +2588,7 @@ export function agentRoutes(const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(existing.companyId,syncedAdapterConfig,- { strictMode: strictSecretsMode },+ { strictMode: strictSecretsMode, adapterType: existing.adapterType },);const actor = getActorInfo(req);const agent = await svc.update(@@ -2643,7 +2659,7 @@ export function agentRoutes(const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(existing.companyId,adapterConfig,- { strictMode: strictSecretsMode },+ { strictMode: strictSecretsMode, adapterType: existing.adapterType },);await svc.update(id,@@ -2711,7 +2727,7 @@ export function agentRoutes(const normalizedAdapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(existing.companyId,result.adapterConfig,- { strictMode: strictSecretsMode },+ { strictMode: strictSecretsMode, adapterType: existing.adapterType },);await svc.update(id,@@ -3184,7 +3200,7 @@ export function agentRoutes(if (!agent) {return;}- const key = await svc.createApiKey(id, req.body.name);+ const key = await svc.createApiKey(id, req.body.name, req.body.scope);await logActivity(db, {companyId: agent.companyId,@@ -3193,7 +3209,7 @@ export function agentRoutes(action: "agent.key_created",entityType: "agent",entityId: agent.id,- details: { keyId: key.id, name: key.name },+ details: { keyId: key.id, name: key.name, scope: key.scope },});res.status(201).json(key);diff --git a/server/src/routes/issues.ts b/server/src/routes/issues.tsindex 95e0a05cfa..2913a05fc0 100644--- a/server/src/routes/issues.ts+++ b/server/src/routes/issues.ts@@ -1889,6 +1889,25 @@ export function issueRoutes(throw forbidden(decision.explanation);}+ function isTaskBridgeKeyActor(req: Request) {+ return req.actor.type === "agent" && req.actor.source === "agent_key" && req.actor.keyScope?.kind === "task_bridge";+ }++ function taskBridgeOriginForActor(req: Request) {+ return isTaskBridgeKeyActor(req) && req.actor.keyId+ ? { originKind: "task_bridge", originId: req.actor.keyId }+ : null;+ }++ async function assertTaskBridgeCreateAllowed(+ req: Request,+ companyId: string,+ assignmentScope: TaskAssignmentAuthorizationScope,+ ) {+ if (!isTaskBridgeKeyActor(req)) return;+ await assertCanAssignTasks(req, companyId, assignmentScope);+ }+async function decideIssueAccess(req: Request,issue: {@@ -2966,6 +2985,10 @@ export function issueRoutes(router.get("/companies/:companyId/issues", async (req, res) => {const companyId = req.params.companyId as string;assertCompanyAccess(req, companyId);+ if (isTaskBridgeKeyActor(req)) {+ res.status(403).json({ error: "Task bridge keys cannot use company-wide issue list APIs" });+ return;+ }const assigneeUserFilterRaw = req.query.assigneeUserId as string | undefined;const touchedByUserFilterRaw = req.query.touchedByUserId as string | undefined;const inboxArchivedByUserFilterRaw = req.query.inboxArchivedByUserId as string | undefined;@@ -3126,6 +3149,10 @@ export function issueRoutes(router.get("/companies/:companyId/issues/count", async (req, res) => {const companyId = req.params.companyId as string;assertCompanyAccess(req, companyId);+ if (isTaskBridgeKeyActor(req)) {+ res.status(403).json({ error: "Task bridge keys cannot use company-wide issue count APIs" });+ return;+ }const attention = req.query.attention as string | undefined;const hasPlanDocument = parseOptionalBooleanQuery(req.query.hasPlanDocument);if (attention !== "blocked") {@@ -5050,7 +5077,7 @@ export function issueRoutes(if (watchdogProductBugFollowUp === false) return;const effectiveParentId = watchdogProductBugFollowUp ? null : rawCreateBody.parentId;let createParent: Awaited<ReturnType<typeof svc.getById>> | null = null;- if (req.actor.type === "agent" && !effectiveParentId && !watchdogProductBugFollowUp) {+ if (req.actor.type === "agent" && !effectiveParentId && !watchdogProductBugFollowUp && !isTaskBridgeKeyActor(req)) {const companyScopeDecision = await access.decide({actor: req.actor,action: "company_scope:read",@@ -5067,7 +5094,7 @@ export function issueRoutes(res.status(404).json({ error: "Parent issue not found" });return;}- if (!(await assertIssueReadAllowed(req, res, createParent))) return;+ if (!isTaskBridgeKeyActor(req) && !(await assertIssueReadAllowed(req, res, createParent))) return;}if (!watchdogProductBugFollowUp &&@@ -5113,17 +5140,19 @@ export function issueRoutes(: {}),};if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, { companyId }, createBody))) return;+ const createAssignmentScope = {+ projectId: await resolveAssignmentProjectId({+ companyId,+ projectId: createBody.projectId,+ parentIssueId: createBody.parentId,+ }),+ parentIssueId: createBody.parentId ?? null,+ assigneeAgentId: createBody.assigneeAgentId ?? null,+ assigneeUserId: rawCreateBody.assigneeUserId ?? null,+ };+ await assertTaskBridgeCreateAllowed(req, companyId, createAssignmentScope);if (rawCreateBody.assigneeAgentId || rawCreateBody.assigneeUserId) {- await assertCanAssignTasks(req, companyId, {- projectId: await resolveAssignmentProjectId({- companyId,- projectId: createBody.projectId,- parentIssueId: createBody.parentId,- }),- parentIssueId: createBody.parentId ?? null,- assigneeAgentId: createBody.assigneeAgentId ?? null,- assigneeUserId: rawCreateBody.assigneeUserId ?? null,- });+ await assertCanAssignTasks(req, companyId, createAssignmentScope);}await assertIssueEnvironmentSelection(companyId, createBody.executionWorkspaceSettings?.environmentId);@@ -5141,6 +5170,7 @@ export function issueRoutes(}, actor);const issue = await svc.create(companyId, {...createBody,+ ...(taskBridgeOriginForActor(req) ?? {}),id: issueId,executionPolicy,...(sourceTrust ? { sourceTrust } : {}),@@ -5258,7 +5288,7 @@ export function issueRoutes(return;}assertCompanyAccess(req, parent.companyId);- if (!(await assertIssueReadAllowed(req, res, parent))) return;+ if (!isTaskBridgeKeyActor(req) && !(await assertIssueReadAllowed(req, res, parent))) return;if (!(await assertTaskWatchdogCreateIssueAllowed(req, res, parent.companyId, parent))) return;if (await assertLowTrustControlPlaneDenied(req, res, parent.companyId, parent)) return;assertNoAgentHostWorkspaceCommandMutation(req, collectIssueWorkspaceCommandPaths(req.body));@@ -5271,13 +5301,15 @@ export function issueRoutes(...(normalizedAssigneeAgentId !== undefined ? { assigneeAgentId: normalizedAssigneeAgentId } : {}),};if (!(await assertCheapRecoveryIssueAssigneeProfileAllowed(req, res, parent, createBody))) return;+ const childAssignmentScope = {+ projectId: createBody.projectId ?? parent.projectId ?? null,+ parentIssueId: parent.id,+ assigneeAgentId: createBody.assigneeAgentId ?? null,+ assigneeUserId: createBody.assigneeUserId ?? null,+ };+ await assertTaskBridgeCreateAllowed(req, parent.companyId, childAssignmentScope);if (req.body.assigneeAgentId || req.body.assigneeUserId) {- await assertCanAssignTasks(req, parent.companyId, {- projectId: createBody.projectId ?? parent.projectId ?? null,- parentIssueId: parent.id,- assigneeAgentId: createBody.assigneeAgentId ?? null,- assigneeUserId: createBody.assigneeUserId ?? null,- });+ await assertCanAssignTasks(req, parent.companyId, childAssignmentScope);}await assertIssueEnvironmentSelection(parent.companyId, createBody.executionWorkspaceSettings?.environmentId);@@ -5300,6 +5332,7 @@ export function issueRoutes(}, actor);const { issue, parentBlockerAdded } = await svc.createChild(parent.id, {...createBody,+ ...(taskBridgeOriginForActor(req) ?? {}),id: issueId,executionPolicy,...(currentSerializedChilddiff --git a/server/src/routes/llms.ts b/server/src/routes/llms.tsindex ff5f36dca4..2d0d75eb60 100644--- a/server/src/routes/llms.ts+++ b/server/src/routes/llms.ts@@ -3,8 +3,13 @@ import type { Db } from "@paperclipai/db";import { AGENT_ICON_NAMES } from "@paperclipai/shared";import { forbidden } from "../errors.js";import { listServerAdapters } from "../adapters/index.js";+import { hermesGatewayAgentConfigurationDoc } from "../adapters/hermes-gateway-doc.js";import { agentService } from "../services/agents.js";+const pluginOnlyAdapterDocs = new Map<string, string>([+ ["hermes_gateway", hermesGatewayAgentConfigurationDoc],+]);+function hasCreatePermission(agent: { role: string; permissions: Record<string, unknown> | null | undefined }) {if (!agent.permissions || typeof agent.permissions !== "object") return false;return Boolean((agent.permissions as Record<string, unknown>).canCreateAgents);@@ -34,6 +39,15 @@ export function llmRoutes(db: Db) {"Installed adapters:",...adapters.map((adapter) => `- ${adapter.type}: /llms/agent-configuration/${adapter.type}.txt`),"",+ "Plugin-only adapter docs:",+ ...Array.from(pluginOnlyAdapterDocs.keys())+ .filter(+ (adapterType) => !adapters.some((adapter) => adapter.type === adapterType),+ )+ .map(+ (adapterType) => `- ${adapterType}: /llms/agent-configuration/${adapterType}.txt`,+ ),+ "","Related API endpoints:","- GET /api/companies/:companyId/agent-configurations","- GET /api/agents/:id/configuration",@@ -72,6 +86,11 @@ export function llmRoutes(db: Db) {const adapterType = req.params.adapterType as string;const adapter = listServerAdapters().find((entry) => entry.type === adapterType);if (!adapter) {+ const pluginOnlyDoc = pluginOnlyAdapterDocs.get(adapterType);+ if (pluginOnlyDoc) {+ res.type("text/plain").send(pluginOnlyDoc);+ return;+ }res.status(404).type("text/plain").send(`Unknown adapter type: ${adapterType}`);return;}diff --git a/server/src/services/agent-secret-bindings.ts b/server/src/services/agent-secret-bindings.tsindex 4afb096b24..9e266f21b6 100644--- a/server/src/services/agent-secret-bindings.ts+++ b/server/src/services/agent-secret-bindings.ts@@ -1,4 +1,18 @@+import { envBindingSchema, type SecretVersionSelector } from "@paperclipai/shared";+interface AgentSecretBindingSyncService {+ syncSecretRefsForTarget?: (+ companyId: string,+ target: { targetType: "agent"; targetId: string },+ refs: Array<{+ secretId: string;+ configPath: string;+ versionSelector?: SecretVersionSelector;+ required?: boolean;+ label?: string | null;+ }>,+ options?: { replaceAll?: boolean },+ ) => Promise<unknown>;syncEnvBindingsForTarget?: (companyId: string,target: { targetType: "agent"; targetId: string; pathPrefix?: string },@@ -11,12 +25,63 @@ function asRecord(value: unknown): Record<string, unknown> | null {return value as Record<string, unknown>;}+function collectSecretRefs(adapterConfig: unknown): Array<{+ secretId: string;+ configPath: string;+ versionSelector?: SecretVersionSelector;+}> {+ const config = asRecord(adapterConfig);+ if (!config) return [];+ const refs: Array<{+ secretId: string;+ configPath: string;+ versionSelector?: SecretVersionSelector;+ }> = [];++ const envValue = asRecord(config.env);+ for (const [key, rawBinding] of Object.entries(envValue ?? {})) {+ const parsed = envBindingSchema.safeParse(rawBinding);+ if (!parsed.success) continue;+ const binding = parsed.data;+ if (typeof binding !== "object" || binding === null || binding.type !== "secret_ref") continue;+ refs.push({+ secretId: binding.secretId,+ configPath: `env.${key}`,+ versionSelector: binding.version ?? "latest",+ });+ }++ for (const [key, rawBinding] of Object.entries(config)) {+ if (key === "env") continue;+ const parsed = envBindingSchema.safeParse(rawBinding);+ if (!parsed.success) continue;+ const binding = parsed.data;+ if (typeof binding !== "object" || binding === null || binding.type !== "secret_ref") continue;+ refs.push({+ secretId: binding.secretId,+ configPath: key,+ versionSelector: binding.version ?? "latest",+ });+ }++ return refs;+}+export async function syncAgentAdapterEnvBindings(input: {secretsSvc: AgentSecretBindingSyncService;companyId: string;agentId: string;adapterConfig: unknown;}) {+ if (input.secretsSvc.syncSecretRefsForTarget) {+ await input.secretsSvc.syncSecretRefsForTarget(+ input.companyId,+ { targetType: "agent", targetId: input.agentId },+ collectSecretRefs(input.adapterConfig),+ { replaceAll: true },+ );+ return;+ }const envValue = asRecord(asRecord(input.adapterConfig)?.env);await input.secretsSvc.syncEnvBindingsForTarget?.(input.companyId,diff --git a/server/src/services/agents.ts b/server/src/services/agents.tsindex 2c69558944..9be0140503 100644--- a/server/src/services/agents.ts+++ b/server/src/services/agents.ts@@ -20,8 +20,10 @@ import {AGENT_DEFAULT_MAX_CONCURRENT_RUNS,getAgentWorkEligibility,isUuidLike,+ normalizeAgentApiKeyScope,normalizeAgentUrlKey,type AgentEligibilityAgent,+ type AgentApiKeyScope,} from "@paperclipai/shared";import { conflict, notFound, unprocessable } from "../errors.js";import { syncAgentAdapterEnvBindings } from "./agent-secret-bindings.js";@@ -428,6 +430,16 @@ export function agentService(db: Db) {const role = (data.role ?? existing.role) as string;normalizedPatch.permissions = normalizeAgentPermissions(data.permissions, role);}+ if (+ Object.prototype.hasOwnProperty.call(normalizedPatch, "adapterConfig") &&+ isPlainRecord(normalizedPatch.adapterConfig)+ ) {+ normalizedPatch.adapterConfig = await secretsSvc.normalizeAdapterConfigForPersistence(+ existing.companyId,+ normalizedPatch.adapterConfig,+ { adapterType: (normalizedPatch.adapterType ?? existing.adapterType) as string },+ );+ }const shouldRecordRevision = Boolean(options?.recordRevision) && hasConfigPatchFields(normalizedPatch);const beforeConfig = shouldRecordRevision ? buildConfigSnapshot(existing) : null;@@ -503,11 +515,24 @@ export function agentService(db: Db) {const role = data.role ?? "general";const normalizedPermissions = normalizeAgentPermissions(data.permissions, role);const runtimeConfig = normalizeRuntimeConfigForNewAgent(data.runtimeConfig);+ const adapterType = data.adapterType ?? "process";+ const adapterConfig = isPlainRecord(data.adapterConfig)+ ? await secretsSvc.normalizeAdapterConfigForPersistence(companyId, data.adapterConfig, { adapterType })+ : {};return db.transaction(async (tx) => {const txDb = tx as unknown as Db;const created = await tx.insert(agents)- .values({ ...data, name: uniqueName, companyId, role, permissions: normalizedPermissions, runtimeConfig })+ .values({+ ...data,+ name: uniqueName,+ companyId,+ role,+ adapterType,+ adapterConfig,+ permissions: normalizedPermissions,+ runtimeConfig,+ }).returning().then((rows) => rows[0]);await syncAgentSecretBindings(created, txDb);@@ -733,7 +758,7 @@ export function agentService(db: Db) {});},- createApiKey: async (id: string, name: string) => {+ createApiKey: async (id: string, name: string, scope: AgentApiKeyScope = { kind: "standard" }) => {const existing = await getById(id);if (!existing) throw notFound("Agent not found");if (existing.status === "pending_approval") {@@ -752,6 +777,7 @@ export function agentService(db: Db) {companyId: existing.companyId,name,keyHash,+ scopeConfig: scope.kind === "standard" ? null : scope,}).returning().then((rows) => rows[0]);@@ -759,6 +785,7 @@ export function agentService(db: Db) {return {id: created.id,name: created.name,+ scope: normalizeAgentApiKeyScope(created.scopeConfig),token,createdAt: created.createdAt,};@@ -769,11 +796,19 @@ export function agentService(db: Db) {.select({id: agentApiKeys.id,name: agentApiKeys.name,+ scopeConfig: agentApiKeys.scopeConfig,createdAt: agentApiKeys.createdAt,revokedAt: agentApiKeys.revokedAt,}).from(agentApiKeys)- .where(eq(agentApiKeys.agentId, id)),+ .where(eq(agentApiKeys.agentId, id))+ .then((rows) => rows.map((row) => ({+ id: row.id,+ name: row.name,+ scope: normalizeAgentApiKeyScope(row.scopeConfig),+ createdAt: row.createdAt,+ revokedAt: row.revokedAt,+ }))),getKeyById: async (keyId: string) =>db@@ -782,12 +817,21 @@ export function agentService(db: Db) {agentId: agentApiKeys.agentId,companyId: agentApiKeys.companyId,name: agentApiKeys.name,+ scopeConfig: agentApiKeys.scopeConfig,createdAt: agentApiKeys.createdAt,revokedAt: agentApiKeys.revokedAt,}).from(agentApiKeys).where(eq(agentApiKeys.id, keyId))- .then((rows) => rows[0] ?? null),+ .then((rows) => {+ const row = rows[0] ?? null;+ return row+ ? {+ ...row,+ scope: normalizeAgentApiKeyScope(row.scopeConfig),+ }+ : null;+ }),revokeKey: async (agentId: string, keyId: string) => {const rows = await dbdiff --git a/server/src/services/authorization.ts b/server/src/services/authorization.tsindex a4c513009c..d3c2a2749c 100644--- a/server/src/services/authorization.ts+++ b/server/src/services/authorization.ts@@ -10,7 +10,7 @@ import {principalPermissionGrants,projects,} from "@paperclipai/db";-import type { PermissionKey, PrincipalType } from "@paperclipai/shared";+import type { AgentApiKeyScope, PermissionKey, PrincipalType, TaskBridgeAgentKeyScope } from "@paperclipai/shared";import { LOW_TRUST_REVIEW_PRESET, extractAgentMentionIds, type LowTrustBoundary } from "@paperclipai/shared";import {LOW_TRUST_ISSUE_ANCESTRY_MAX_DEPTH,@@ -29,6 +29,8 @@ export type AuthorizationActor =isInstanceAdmin?: boolean;agentId?: string | null;companyId?: string | null;+ keyId?: string | null;+ keyScope?: AgentApiKeyScope | null;runId?: string | null;source?:| "local_implicit"@@ -66,6 +68,8 @@ export type AuthorizationResource =parentIssueId?: string | null;assigneeAgentId?: string | null;assigneeUserId?: string | null;+ originKind?: string | null;+ originId?: string | null;status?: string | null;};@@ -211,6 +215,8 @@ type IssueAuthorizationRow = {assigneeUserId: string | null;status: string;executionPolicy: unknown;+ originKind: string | null;+ originId: string | null;};function evaluateAuthorizationPolicyForAssignment(@@ -550,6 +556,8 @@ export function authorizationService(db: Db) {assigneeUserId: issues.assigneeUserId,status: issues.status,executionPolicy: issues.executionPolicy,+ originKind: issues.originKind,+ originId: issues.originId,}).from(issues).where(eq(issues.id, issueId))@@ -802,6 +810,130 @@ export function authorizationService(db: Db) {return null;}+ function taskBridgeScopeIds(+ scope: TaskBridgeAgentKeyScope,+ singularKey: "projectId" | "parentIssueId",+ pluralKey: "projectIds" | "parentIssueIds",+ ) {+ return [+ ...(typeof scope[singularKey] === "string" ? [scope[singularKey]] : []),+ ...(Array.isArray(scope[pluralKey]) ? scope[pluralKey] : []),+ ].filter((value): value is string => typeof value === "string" && value.length > 0);+ }++ async function parentIssueMatchesTaskBridgeBoundary(+ parentIssueId: string | null | undefined,+ companyId: string,+ allowedParentIssueIds: string[],+ ) {+ if (!parentIssueId || allowedParentIssueIds.length === 0) return false;+ if (allowedParentIssueIds.includes(parentIssueId)) return true;+ for (const rootIssueId of allowedParentIssueIds) {+ if (await issueIdIsDescendantOf(parentIssueId, rootIssueId, companyId)) return true;+ }+ return false;+ }++ async function issueMatchesTaskBridgeCreateBoundary(+ scope: TaskBridgeAgentKeyScope,+ resource: Extract<AuthorizationResource, { type: "issue" }>,+ ) {+ const allowedProjectIds = taskBridgeScopeIds(scope, "projectId", "projectIds");+ const allowedParentIssueIds = taskBridgeScopeIds(scope, "parentIssueId", "parentIssueIds");+ if (resource.projectId && allowedProjectIds.includes(resource.projectId)) return true;+ if (await parentIssueMatchesTaskBridgeBoundary(resource.parentIssueId, resource.companyId, allowedParentIssueIds)) {+ return true;+ }+ if (resource.parentIssueId && allowedProjectIds.length > 0) {+ const parent = await loadIssue(resource.parentIssueId);+ if (parent?.companyId === resource.companyId && parent.projectId && allowedProjectIds.includes(parent.projectId)) {+ return true;+ }+ }+ return false;+ }++ async function issueMatchesTaskBridgeWriteBoundary(input: {+ actorAgentId: string;+ keyId: string;+ resource: Extract<AuthorizationResource, { type: "issue" }>;+ }) {+ const issue = input.resource.issueId ? await loadIssue(input.resource.issueId) : null;+ const assigneeAgentId = issue?.assigneeAgentId ?? input.resource.assigneeAgentId ?? null;+ if (assigneeAgentId === input.actorAgentId) return true;+ const originKind = issue?.originKind ?? input.resource.originKind ?? null;+ const originId = issue?.originId ?? input.resource.originId ?? null;+ return originKind === "task_bridge" && originId === input.keyId;+ }++ async function decideTaskBridgeAccess(input: {+ actorAgentId: string;+ action: AuthorizationAction;+ resource: AuthorizationResource;+ scope: TaskBridgeAgentKeyScope;+ keyId: string;+ }): Promise<AuthorizationDecision | null> {+ const denyBridge = (explanation: string) =>+ deny({+ action: input.action,+ reason: "deny_scope",+ explanation,+ });+ const allowBridge = (explanation: string) =>+ allow({+ action: input.action,+ reason: "allow_explicit_grant",+ explanation,+ });++ if (+ input.action === "company_scope:read" ||+ input.action === "agent:read" ||+ input.action === "agent:wake" ||+ input.action === "project:read" ||+ input.action === "runtime:manage" ||+ input.action === "secrets:read"+ ) {+ return denyBridge("Task bridge keys cannot use company-wide, peer-agent, project, runtime, or secret APIs.");+ }++ if (input.action === "tasks:assign") {+ if (input.resource.type !== "issue") {+ return denyBridge("Task bridge assignment requires an issue resource.");+ }+ if (!(await issueMatchesTaskBridgeCreateBoundary(input.scope, input.resource))) {+ return denyBridge("Task bridge key is outside its approved parent or project boundary.");+ }+ if (input.resource.assigneeUserId) {+ return denyBridge("Task bridge keys cannot assign work to board users.");+ }+ const allowedAssigneeAgentIds = input.scope.allowedAssigneeAgentIds ?? [];+ if (+ input.resource.assigneeAgentId &&+ input.resource.assigneeAgentId !== input.actorAgentId &&+ !allowedAssigneeAgentIds.includes(input.resource.assigneeAgentId)+ ) {+ return denyBridge("Task bridge key cannot assign work to that agent.");+ }+ return allowBridge("Allowed by task bridge create boundary.");+ }++ if (input.action === "issue:read" || input.action === "issue:comment" || input.action === "issue:mutate") {+ if (input.resource.type !== "issue") {+ return denyBridge("Task bridge issue access requires an issue resource.");+ }+ return await issueMatchesTaskBridgeWriteBoundary({+ actorAgentId: input.actorAgentId,+ keyId: input.keyId,+ resource: input.resource,+ })+ ? allowBridge("Allowed for bridge-created or assigned issue.")+ : denyBridge("Task bridge key can only access assigned or bridge-created issues.");+ }++ return denyBridge("Task bridge key cannot use this API action.");+ }+async function assignmentTargetIsInCompany(resource: AuthorizationResource) {if (resource.type !== "issue") return true;if (resource.assigneeAgentId) {@@ -1183,6 +1315,25 @@ export function authorizationService(db: Db) {});}+ if (input.actor.source === "agent_key" && input.actor.keyScope?.kind === "task_bridge") {+ const keyId = input.actor.keyId ?? null;+ if (!keyId) {+ return deny({+ action: input.action,+ reason: "deny_scope",+ explanation: "Task bridge key context is missing.",+ });+ }+ const taskBridgeDecision = await decideTaskBridgeAccess({+ actorAgentId,+ action: input.action,+ resource: input.resource,+ scope: input.actor.keyScope,+ keyId,+ });+ if (taskBridgeDecision) return taskBridgeDecision;+ }+const lowTrustDecision = await decideLowTrustAccess({actorAgentId,action: input.action,diff --git a/server/src/services/company-portability.ts b/server/src/services/company-portability.tsindex 1024a871b7..b1c1c7216c 100644--- a/server/src/services/company-portability.ts+++ b/server/src/services/company-portability.ts@@ -3050,7 +3050,7 @@ export function companyPortabilityService(db: Db, storage?: StorageService) {const normalizedAdapterConfig = await secrets.normalizeAdapterConfigForPersistence(companyId,nextAdapterConfig,- { strictMode: strictSecretsMode },+ { strictMode: strictSecretsMode, adapterType: effectiveAdapterType },);await assertImportAdapterConfigConstraints(effectiveAdapterType, normalizedAdapterConfig);return {diff --git a/server/src/services/heartbeat.ts b/server/src/services/heartbeat.tsindex 197b11d8c6..81c4a3af9f 100644--- a/server/src/services/heartbeat.ts+++ b/server/src/services/heartbeat.ts@@ -412,7 +412,10 @@ const INLINE_BASE64_IMAGE_DATA_RE = /("type":"image","source":\{"type":"base64",type RuntimeConfigSecretResolver = Pick<ReturnType<typeof secretService>,- "resolveAdapterConfigForRuntime" | "resolveEnvBindings" | "collectMissingRuntimeBindings"+ | "resolveAdapterConfigForRuntime"+ | "resolveEnvBindings"+ | "collectMissingRuntimeBindings"+ | "collectMissingAdapterConfigRuntimeBindings">;function formatMissingBindingForOperator(missing: MissingRuntimeBinding): string {@@ -494,6 +497,7 @@ function assertLowTrustEnvConfigAllowed(envValue: unknown, source: string) {export async function resolveExecutionRunAdapterConfig(input: {companyId: string;agentId?: string | null;+ adapterType?: string | null;issueId?: string | null;heartbeatRunId?: string | null;environmentId?: string | null;@@ -574,6 +578,16 @@ export async function resolveExecutionRunAdapterConfig(input: {{ consumerType: "agent", consumerId: input.agentId },)),);+ if (typeof input.secretsSvc.collectMissingAdapterConfigRuntimeBindings === "function") {+ missingBindings.push(+ ...(await input.secretsSvc.collectMissingAdapterConfigRuntimeBindings(+ input.companyId,+ executionRunConfig,+ input.adapterType ?? null,+ { consumerType: "agent", consumerId: input.agentId },+ )),+ );+ }}if (projectEnv && input.projectId) {missingBindings.push(@@ -666,6 +680,7 @@ export async function resolveExecutionRunAdapterConfig(input: {...(lowTrustAllowedBindingIds !== undefined ? { allowedBindingIds: lowTrustAllowedBindingIds } : {}),}: undefined,+ { adapterType: input.adapterType ?? null },);if (Object.keys(environmentEnvResolution.env).length > 0) {resolvedConfig.env = {@@ -3140,6 +3155,13 @@ export function buildPaperclipTaskMarkdown(input: {workMode?: string | null;description?: string | null;} | null;+ ancestors?: Array<{+ id: string;+ identifier?: string | null;+ title?: string | null;+ status?: string | null;+ priority?: string | null;+ }> | null;wakeComment?: {id: string;body: string;@@ -3160,6 +3182,7 @@ export function buildPaperclipTaskMarkdown(input: {return [fence + "text", value, fence].join("\n");};const issue = input.issue;+ const ancestors = (input.ancestors ?? []).slice(0, 6);const wakeComment = input.wakeComment ?? null;const acceptedPlanContinuation =!wakeComment &&@@ -3212,6 +3235,19 @@ export function buildPaperclipTaskMarkdown(input: {lines.push("", "Issue description:", fenceTaskText(description));}}+ if (ancestors.length > 0) {+ lines.push("", "Authoritative parent / ancestor context:");+ for (const [index, ancestor] of ancestors.entries()) {+ const label = ancestor.identifier || ancestor.id;+ const status = ancestor.status ? ` (${ancestor.status})` : "";+ const priority = ancestor.priority ? ` [${ancestor.priority}]` : "";+ const title = ancestor.title ? ` ${ancestor.title}` : "";+ lines.push(`- ${index === 0 ? "Parent" : `Ancestor ${index + 1}`}: ${label}${title}${status}${priority}`);+ }+ if ((input.ancestors ?? []).length > ancestors.length) {+ lines.push(`- [ancestor context truncated after ${ancestors.length} entries]`);+ }+ }if (wakeComment?.body.trim()) {lines.push("", "Latest wake comment:", fenceTaskText(wakeComment.body.trim()));}@@ -8647,6 +8683,9 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})wakeCommentContext && !exposeLowTrustRaw? sanitizeQuarantinedCommentForHigherTrust(wakeCommentContext): wakeCommentContext;+ const issueAncestors = issueRef+ ? await issuesSvc.getAncestors(issueRef.id)+ : [];if (continuationSummary) {context.paperclipContinuationSummary = {key: safeContinuationSummary!.key,@@ -8692,6 +8731,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})description: issueRef.description,}: null,+ ancestors: issueAncestors,wakeComment: safeWakeCommentContext,interaction: {kind: readNonEmptyString(context.interactionKind),@@ -8918,6 +8958,7 @@ export function heartbeatService(db: Db, options: HeartbeatServiceOptions = {})const { resolvedConfig, secretKeys, secretManifest } = await resolveExecutionRunAdapterConfig({companyId: agent.companyId,agentId: agent.id,+ adapterType: agent.adapterType,issueId,heartbeatRunId: run.id,environmentId: selectedEnvironmentForConfig?.id ?? null,diff --git a/server/src/services/secrets.ts b/server/src/services/secrets.tsindex 25b1228d8e..69fefbbe3d 100644--- a/server/src/services/secrets.ts+++ b/server/src/services/secrets.ts@@ -1,3 +1,4 @@+import { randomUUID } from "node:crypto";import { and, desc, eq, inArray, like, ne, notInArray, or, sql } from "drizzle-orm";import type { Db } from "@paperclipai/db";import {@@ -55,6 +56,7 @@ import type {} from "../secrets/types.js";import { isSecretProviderClientError } from "../secrets/types.js";import { authorizationService } from "./authorization.js";+import { findActiveServerAdapter } from "../adapters/index.js";const ENV_KEY_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;const SENSITIVE_ENV_KEY_RE =@@ -64,6 +66,9 @@ const COMING_SOON_SECRET_PROVIDERS: ReadonlySet<SecretProvider> = new Set(["gcp_secret_manager","vault",]);+const FALLBACK_ADAPTER_SCHEMA_SECRET_FIELDS: Readonly<Record<string, readonly string[]>> = {+ hermes_gateway: ["apiKey"],+};type DbTransaction = Parameters<Parameters<Db["transaction"]>[0]>[0];type SecretBindingDb = Pick<Db | DbTransaction, "select" | "delete" | "insert">;@@ -357,6 +362,11 @@ export function secretService(db: Db) {strictMode?: boolean;fieldPath?: string;};+ type NormalizeAdapterConfigOptions = {+ strictMode?: boolean;+ adapterType?: string | null;+ actor?: { userId?: string | null; agentId?: string | null };+ };async function getById(id: string, source: Pick<Db | DbTransaction, "select"> = db) {return source@@ -809,16 +819,210 @@ export function secretService(db: Db) {async function normalizeAdapterConfigForPersistenceInternal(companyId: string,adapterConfig: Record<string, unknown>,- opts?: { strictMode?: boolean },+ opts?: NormalizeAdapterConfigOptions,) {const normalized = { ...adapterConfig };- if (!Object.prototype.hasOwnProperty.call(adapterConfig, "env")) {- return normalized;+ if (Object.prototype.hasOwnProperty.call(adapterConfig, "env")) {+ normalized.env = await normalizeEnvConfig(companyId, adapterConfig.env, opts);+ }+ const secretFieldKeys = await listAdapterSchemaSecretFieldKeys(opts?.adapterType);+ for (const key of secretFieldKeys) {+ if (!Object.prototype.hasOwnProperty.call(adapterConfig, key)) continue;+ const value = await normalizeSchemaSecretFieldForPersistence(companyId, {+ adapterType: opts?.adapterType ?? null,+ key,+ rawValue: adapterConfig[key],+ actor: opts?.actor,+ });+ if (value === undefined) {+ delete normalized[key];+ } else {+ normalized[key] = value;+ }}- normalized.env = await normalizeEnvConfig(companyId, adapterConfig.env, opts);return normalized;}+ async function listAdapterSchemaSecretFieldKeys(adapterType: string | null | undefined): Promise<string[]> {+ if (!adapterType) return [];+ const adapter = findActiveServerAdapter(adapterType);+ const fallback = [...(FALLBACK_ADAPTER_SCHEMA_SECRET_FIELDS[adapterType] ?? [])];+ if (!adapter?.getConfigSchema) return fallback;+ try {+ const schema = await adapter.getConfigSchema();+ return [...new Set([+ ...fallback,+ ...schema.fields+ .filter((field) => field.meta?.secret === true)+ .map((field) => field.key),+ ])];+ } catch (err) {+ logger.warn({ err, adapterType }, "adapter config schema unavailable while normalizing secret fields");+ return fallback;+ }+ }++ async function normalizeSchemaSecretFieldForPersistence(+ companyId: string,+ input: {+ adapterType: string | null;+ key: string;+ rawValue: unknown;+ actor?: { userId?: string | null; agentId?: string | null };+ },+ ): Promise<EnvBinding | undefined> {+ if (input.rawValue === null || input.rawValue === undefined) return undefined;+ const parsed = envBindingSchema.safeParse(input.rawValue);+ if (!parsed.success) {+ throw unprocessable(`${input.key} must be a string, plain binding, or secret reference`);+ }+ const binding = canonicalizeBinding(parsed.data as EnvBinding);+ if (binding.type === "secret_ref") {+ await assertSecretInCompany(companyId, binding.secretId);+ return {+ type: "secret_ref",+ secretId: binding.secretId,+ version: binding.version,+ };+ }+ const value = binding.value.trim();+ if (!value) return undefined;+ if (value === REDACTED_SENTINEL) {+ throw unprocessable(`Refusing to persist redacted placeholder for key: ${input.key}`);+ }+ const id = randomUUID();+ const adapterPart = normalizeSecretKey(input.adapterType ?? "adapter");+ const fieldPart = normalizeSecretKey(input.key);+ const secret = await createManagedLocalSecret(companyId, {+ name: `${adapterPart}.${fieldPart}.${id}`,+ key: `${adapterPart}.${fieldPart}.${id}`,+ value,+ description: `Adapter config secret for ${input.adapterType ?? "adapter"}.${input.key}`,+ }, input.actor);+ return {+ type: "secret_ref",+ secretId: secret.id,+ version: "latest",+ };+ }++ async function createManagedLocalSecret(+ companyId: string,+ input: {+ name: string;+ key: string;+ value: string;+ description?: string | null;+ },+ actor?: { userId?: string | null; agentId?: string | null },+ ) {+ const existing = await getByName(companyId, input.name);+ if (existing) throw conflict(`Secret already exists: ${input.name}`);+ const key = normalizeSecretKey(input.key);+ if (!key) throw unprocessable("Secret key is required");+ const duplicateKey = await db+ .select()+ .from(companySecrets)+ .where(and(+ eq(companySecrets.companyId, companyId),+ eq(companySecrets.key, key),+ ne(companySecrets.status, "deleted"),+ ))+ .then((rows) => rows[0] ?? null);+ if (duplicateKey) throw conflict(`Secret key already exists: ${key}`);++ const provider = getSecretProvider("local_encrypted");+ const providerConfig = await getSelectableRuntimeProviderConfig({+ companyId,+ provider: "local_encrypted",+ providerConfigId: null,+ });+ const providerWriteContext = {+ companyId,+ secretKey: key,+ secretName: input.name,+ version: 1,+ };+ const reservedSecret = await db+ .insert(companySecrets)+ .values({+ companyId,+ key,+ name: input.name,+ provider: "local_encrypted",+ providerConfigId: null,+ status: "archived",+ managedMode: "paperclip_managed",+ externalRef: null,+ providerMetadata: null,+ latestVersion: 0,+ description: input.description ?? null,+ createdByAgentId: actor?.agentId ?? null,+ createdByUserId: actor?.userId ?? null,+ })+ .returning()+ .then((rows) => rows[0]);++ let prepared: PreparedSecretVersion | null = null;+ try {+ prepared = await provider.createSecret({+ value: input.value,+ externalRef: null,+ providerConfig,+ context: providerWriteContext,+ });+ const preparedSecret = prepared;+ await db.insert(companySecretVersions).values({+ secretId: reservedSecret.id,+ version: 1,+ material: preparedSecret.material,+ valueSha256: preparedSecret.valueSha256,+ fingerprintSha256: preparedSecret.fingerprintSha256 ?? preparedSecret.valueSha256,+ providerVersionRef: preparedSecret.providerVersionRef ?? null,+ status: "disabled",+ createdByAgentId: actor?.agentId ?? null,+ createdByUserId: actor?.userId ?? null,+ });+ return await db.transaction(async (tx) => {+ await tx+ .update(companySecretVersions)+ .set({ status: "current" })+ .where(and(+ eq(companySecretVersions.secretId, reservedSecret.id),+ eq(companySecretVersions.version, 1),+ ));+ const secret = await tx+ .update(companySecrets)+ .set({+ status: "active",+ externalRef: preparedSecret.externalRef,+ latestVersion: 1,+ lastRotatedAt: new Date(),+ updatedAt: new Date(),+ })+ .where(eq(companySecrets.id, reservedSecret.id))+ .returning()+ .then((rows) => rows[0]);+ if (!secret) throw notFound("Secret not found");+ return secret;+ });+ } catch (error) {+ if (prepared) {+ await cleanupPreparedProviderWrite({+ provider,+ prepared,+ providerConfig,+ context: providerWriteContext,+ mode: "delete",+ operation: "adapter_config_secret.create_rollback",+ }).catch(() => false);+ }+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);+ await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);+ throw error;+ }+ }+function collectTargetIds(bindings: Array<typeof companySecretBindings.$inferSelect>,targetType: SecretBindingTargetType,@@ -1817,9 +2021,11 @@ export function secretService(db: Db) {operation: "create.prepare_rollback",});if (cleaned) {+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);}} else {+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);}throw error;@@ -1862,9 +2068,11 @@ export function secretService(db: Db) {operation: "create.rollback",});if (cleaned) {+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);}} else {+ await db.delete(companySecretVersions).where(eq(companySecretVersions.secretId, reservedSecret.id)).catch(() => undefined);await db.delete(companySecrets).where(eq(companySecrets.id, reservedSecret.id)).catch(() => undefined);}throw error;@@ -2159,6 +2367,7 @@ export function secretService(db: Db) {required?: boolean;label?: string | null;}>,+ options?: { replaceAll?: boolean },) => {const normalizedRefs: Array<{secretId: string;@@ -2181,7 +2390,17 @@ export function secretService(db: Db) {const pathPrefixes = [...new Set(normalizedRefs.map((ref) => ref.configPath.split(".")[0]))];await db.transaction(async (tx) => {- if (pathPrefixes.length > 0) {+ if (options?.replaceAll) {+ await tx+ .delete(companySecretBindings)+ .where(+ and(+ eq(companySecretBindings.companyId, companyId),+ eq(companySecretBindings.targetType, target.targetType),+ eq(companySecretBindings.targetId, target.targetId),+ ),+ );+ } else if (pathPrefixes.length > 0) {for (const pathPrefix of pathPrefixes) {await tx.delete(companySecretBindings)@@ -2351,7 +2570,7 @@ export function secretService(db: Db) {normalizeAdapterConfigForPersistence: async (companyId: string,adapterConfig: Record<string, unknown>,- opts?: { strictMode?: boolean },+ opts?: NormalizeAdapterConfigOptions,) => normalizeAdapterConfigForPersistenceInternal(companyId, adapterConfig, opts),normalizeEnvBindingsForPersistence: async (@@ -2363,7 +2582,7 @@ export function secretService(db: Db) {normalizeHireApprovalPayloadForPersistence: async (companyId: string,payload: Record<string, unknown>,- opts?: { strictMode?: boolean },+ opts?: NormalizeAdapterConfigOptions,) => {const normalized = { ...payload };const adapterConfig = asRecord(payload.adapterConfig);@@ -2473,52 +2692,121 @@ export function secretService(db: Db) {}));},+ collectMissingAdapterConfigRuntimeBindings: async (+ companyId: string,+ adapterConfig: Record<string, unknown>,+ adapterType: string | null | undefined,+ context: Omit<SecretConsumerContext, "configPath">,+ ): Promise<MissingRuntimeBinding[]> => {+ const secretFieldKeys = await listAdapterSchemaSecretFieldKeys(adapterType);+ const secretRefs = secretFieldKeys.flatMap((key) => {+ const parsed = envBindingSchema.safeParse(adapterConfig[key]);+ if (!parsed.success) return [];+ const binding = canonicalizeBinding(parsed.data as EnvBinding);+ if (binding.type !== "secret_ref") return [];+ return [{ key, configPath: key, secretId: binding.secretId }];+ });+ if (secretRefs.length === 0) return [];+ const bindingChecks = await Promise.all(secretRefs.map(async (entry) => ({+ entry,+ found: await getBinding({+ companyId,+ secretId: entry.secretId,+ consumerType: context.consumerType,+ consumerId: context.consumerId,+ configPath: entry.configPath,+ }),+ })));+ const missingEntries = bindingChecks+ .filter((check) => !check.found)+ .map((check) => check.entry);+ if (missingEntries.length === 0) return [];++ const secretRows = await Promise.all(+ [...new Set(missingEntries.map((entry) => entry.secretId))].map(async (secretId) => [+ secretId,+ await getById(secretId).catch(() => null),+ ] as const),+ );+ const secretsById = new Map(secretRows);++ return missingEntries.map((entry) => ({+ consumerType: context.consumerType,+ consumerId: context.consumerId,+ configPath: entry.configPath,+ envKey: entry.key,+ secretId: entry.secretId,+ secretName: secretsById.get(entry.secretId)?.name ?? null,+ }));+ },+resolveAdapterConfigForRuntime: async (companyId: string,adapterConfig: Record<string, unknown>,context?: Omit<SecretConsumerContext, "configPath">,+ opts?: { adapterType?: string | null },): Promise<{ config: Record<string, unknown>; secretKeys: Set<string>; manifest: RuntimeSecretManifestEntry[] }> => {const resolved = { ...adapterConfig };const secretKeys = new Set<string>();const manifest: RuntimeSecretManifestEntry[] = [];- if (!Object.prototype.hasOwnProperty.call(adapterConfig, "env")) {- return { config: resolved, secretKeys, manifest };- }- const record = asRecord(adapterConfig.env);- if (!record) {- resolved.env = {};- return { config: resolved, secretKeys, manifest };- }- const env: Record<string, string> = {};- for (const [key, rawBinding] of Object.entries(record)) {- if (!ENV_KEY_RE.test(key)) {- throw unprocessable(`Invalid environment variable name: ${key}`);- }- const parsed = envBindingSchema.safeParse(rawBinding);- if (!parsed.success) {- throw unprocessable(`Invalid environment binding for key: ${key}`);- }- const binding = canonicalizeBinding(parsed.data as EnvBinding);- if (binding.type === "plain") {- env[key] = binding.value;+ if (Object.prototype.hasOwnProperty.call(adapterConfig, "env")) {+ const record = asRecord(adapterConfig.env);+ if (!record) {+ resolved.env = {};} else {- const secretResolution = await resolveSecretValueInternal(- companyId,- binding.secretId,- binding.version,- context- ? {- bindingContext: { ...context, configPath: `env.${key}` },- accessContext: { ...context, configPath: `env.${key}` },- }- : undefined,- );- env[key] = secretResolution.value;- manifest.push(secretResolution.manifestEntry);- secretKeys.add(key);+ const env: Record<string, string> = {};+ for (const [key, rawBinding] of Object.entries(record)) {+ if (!ENV_KEY_RE.test(key)) {+ throw unprocessable(`Invalid environment variable name: ${key}`);+ }+ const parsed = envBindingSchema.safeParse(rawBinding);+ if (!parsed.success) {+ throw unprocessable(`Invalid environment binding for key: ${key}`);+ }+ const binding = canonicalizeBinding(parsed.data as EnvBinding);+ if (binding.type === "plain") {+ env[key] = binding.value;+ } else {+ const secretResolution = await resolveSecretValueInternal(+ companyId,+ binding.secretId,+ binding.version,+ context+ ? {+ bindingContext: { ...context, configPath: `env.${key}` },+ accessContext: { ...context, configPath: `env.${key}` },+ }+ : undefined,+ );+ env[key] = secretResolution.value;+ manifest.push(secretResolution.manifestEntry);+ secretKeys.add(key);+ }+ }+ resolved.env = env;}}- resolved.env = env;+ const secretFieldKeys = await listAdapterSchemaSecretFieldKeys(opts?.adapterType);+ for (const key of secretFieldKeys) {+ const parsed = envBindingSchema.safeParse(adapterConfig[key]);+ if (!parsed.success) continue;+ const binding = canonicalizeBinding(parsed.data as EnvBinding);+ if (binding.type === "plain") continue;+ const secretResolution = await resolveSecretValueInternal(+ companyId,+ binding.secretId,+ binding.version,+ context+ ? {+ bindingContext: { ...context, configPath: key },+ accessContext: { ...context, configPath: key },+ }+ : undefined,+ );+ resolved[key] = secretResolution.value;+ manifest.push(secretResolution.manifestEntry);+ secretKeys.add(key);+ }return { config: resolved, secretKeys, manifest };},};diff --git a/server/src/types/express.d.ts b/server/src/types/express.d.tsindex 17f94e752e..4d04d1cc48 100644--- a/server/src/types/express.d.ts+++ b/server/src/types/express.d.ts@@ -1,5 +1,7 @@export {};+import type { AgentApiKeyScope } from "@paperclipai/shared";+declare global {namespace Express {interface Request {@@ -18,6 +20,7 @@ declare global {}>;isInstanceAdmin?: boolean;keyId?: string;+ keyScope?: AgentApiKeyScope;runId?: string;source?: "local_implicit" | "session" | "board_key" | "agent_key" | "agent_jwt" | "cloud_tenant" | "none";};diff --git a/tsconfig.json b/tsconfig.jsonindex e597c33111..e043a6a490 100644--- a/tsconfig.json+++ b/tsconfig.json@@ -9,6 +9,8 @@{ "path": "./packages/adapters/claude-local" },{ "path": "./packages/adapters/codex-local" },{ "path": "./packages/adapters/cursor-local" },+ { "path": "./packages/adapters/hermes-gateway" },+ { "path": "./packages/adapters/hermes" },{ "path": "./packages/adapters/droid-local" },{ "path": "./packages/adapters/openclaw-gateway" },{ "path": "./packages/adapters/opencode-local" },diff --git a/ui/package.json b/ui/package.jsonindex e20a5751ad..b52f0b6e32 100644--- a/ui/package.json+++ b/ui/package.json@@ -46,13 +46,13 @@"@paperclipai/adapter-pi-local": "workspace:*","@paperclipai/adapter-utils": "workspace:*","@paperclipai/shared": "workspace:*",+ "@paperclipai/hermes-paperclip-adapter": "workspace:*","@radix-ui/react-slot": "^1.2.4","@tailwindcss/typography": "^0.5.19","@tanstack/react-query": "^5.90.21","class-variance-authority": "^0.7.1","clsx": "^2.1.1","cmdk": "^1.1.1",- "hermes-paperclip-adapter": "^0.3.0","i18next": "^26.3.1","lexical": "0.35.0","lucide-react": "^0.577.0",diff --git a/ui/src/adapters/adapter-display-registry.ts b/ui/src/adapters/adapter-display-registry.tsindex e710d07b9c..17a20dca8f 100644--- a/ui/src/adapters/adapter-display-registry.ts+++ b/ui/src/adapters/adapter-display-registry.ts@@ -16,7 +16,6 @@ import {Cpu,} from "lucide-react";import { OpenCodeLogoIcon } from "@/components/OpenCodeLogoIcon";-import { HermesIcon } from "@/components/HermesIcon";// ---------------------------------------------------------------------------// Type suffix parsing@@ -83,16 +82,22 @@ const adapterDisplayMap: Record<string, AdapterDisplayInfo> = {description: "Local Grok Build agent",icon: Bot,},+ hermes_gateway: {+ label: "Hermes",+ description: "Remote Hermes API server",+ icon: Bot,+ hideFromVisualSelection: true,+ },+ hermes_local: {+ label: "Hermes",+ description: "Local Hermes agent",+ icon: Bot,+ },opencode_local: {label: "OpenCode",description: "Local multi-provider agent",icon: OpenCodeLogoIcon,},- hermes_local: {- label: "Hermes Agent",- description: "Local Hermes CLI agent",- icon: HermesIcon,- },pi_local: {label: "Pi",description: "Local Pi agent",diff --git a/ui/src/adapters/hermes-gateway/index.ts b/ui/src/adapters/hermes-gateway/index.tsnew file mode 100644index 0000000000..3aa46ec063--- /dev/null+++ b/ui/src/adapters/hermes-gateway/index.ts@@ -0,0 +1,11 @@+import type { UIAdapterModule } from "../types";+import { parseStdoutLine as parseHermesGatewayStdoutLine } from "@paperclipai/hermes-paperclip-adapter/gateway/ui";+import { SchemaConfigFields, buildSchemaAdapterConfig } from "../schema-config-fields";++export const hermesGatewayUIAdapter: UIAdapterModule = {+ type: "hermes_gateway",+ label: "Hermes Gateway",+ parseStdoutLine: parseHermesGatewayStdoutLine,+ ConfigFields: SchemaConfigFields,+ buildAdapterConfig: buildSchemaAdapterConfig,+};diff --git a/ui/src/adapters/hermes-local/config-fields.tsx b/ui/src/adapters/hermes-local/config-fields.tsxdeleted file mode 100644index 4b80704365..0000000000--- a/ui/src/adapters/hermes-local/config-fields.tsx+++ /dev/null@@ -1,49 +0,0 @@-import type { AdapterConfigFieldsProps } from "../types";-import {- Field,- DraftInput,-} from "../../components/agent-config-primitives";-import { ChoosePathButton } from "../../components/PathInstructionsModal";--const inputClass =- "w-full rounded-md border border-border px-2.5 py-1.5 bg-transparent outline-none text-sm font-mono placeholder:text-muted-foreground/40";-const instructionsFileHint =- "Absolute path to a markdown file (e.g. AGENTS.md) that defines this agent's behavior. Injected into the system prompt at runtime.";--export function HermesLocalConfigFields({- isCreate,- values,- set,- config,- eff,- mark,- hideInstructionsFile,-}: AdapterConfigFieldsProps) {- if (hideInstructionsFile) return null;- return (- <Field label="Agent instructions file" hint={instructionsFileHint}>- <div className="flex items-center gap-2">- <DraftInput- value={- isCreate- ? values!.instructionsFilePath ?? ""- : eff(- "adapterConfig",- "instructionsFilePath",- String(config.instructionsFilePath ?? ""),- )- }- onCommit={(v) =>- isCreate- ? set!({ instructionsFilePath: v })- : mark("adapterConfig", "instructionsFilePath", v || undefined)- }- immediate- className={inputClass}- placeholder="/absolute/path/to/AGENTS.md"- />- <ChoosePathButton />- </div>- </Field>- );-}diff --git a/ui/src/adapters/hermes-local/index.ts b/ui/src/adapters/hermes-local/index.tsindex a74491748b..6eb325aeb7 100644--- a/ui/src/adapters/hermes-local/index.ts+++ b/ui/src/adapters/hermes-local/index.ts@@ -1,11 +1,10 @@import type { UIAdapterModule } from "../types";-import { parseHermesStdoutLine } from "hermes-paperclip-adapter/ui";-import { buildHermesConfig } from "hermes-paperclip-adapter/ui";+import { parseHermesStdoutLine, buildHermesConfig } from "@paperclipai/hermes-paperclip-adapter/ui";import { SchemaConfigFields } from "../schema-config-fields";export const hermesLocalUIAdapter: UIAdapterModule = {type: "hermes_local",- label: "Hermes Agent",+ label: "Hermes",parseStdoutLine: parseHermesStdoutLine,ConfigFields: SchemaConfigFields,buildAdapterConfig: buildHermesConfig,diff --git a/ui/src/adapters/registry.test.ts b/ui/src/adapters/registry.test.tsindex 6d30f6b0a6..2d36af655e 100644--- a/ui/src/adapters/registry.test.ts+++ b/ui/src/adapters/registry.test.ts@@ -5,6 +5,7 @@ import {getUIAdapter,listUIAdapters,registerUIAdapter,+ syncExternalAdapters,unregisterUIAdapter,} from "./registry";import { processUIAdapter } from "./process";@@ -21,10 +22,12 @@ const externalUIAdapter: UIAdapterModule = {describe("ui adapter registry", () => {beforeEach(() => {unregisterUIAdapter("external_test");+ syncExternalAdapters([]);});afterEach(() => {unregisterUIAdapter("external_test");+ syncExternalAdapters([]);});it("registers adapters for lookup and listing", () => {@@ -48,4 +51,30 @@ describe("ui adapter registry", () => {// But it uses the schema-based config fields for external adapter forms.expect(fallback.ConfigFields).toBe(SchemaConfigFields);});++ it("restores built-in Hermes adapters when external overrides are paused or removed", () => {+ for (const type of ["hermes_local", "hermes_gateway"]) {+ const builtin = getUIAdapter(type);++ syncExternalAdapters([{ type, label: "External Hermes" }]);++ const overridden = getUIAdapter(type);+ expect(overridden).not.toBe(builtin);+ expect(overridden.type).toBe(type);+ expect(overridden.label).toBe("External Hermes");+ expect(overridden.ConfigFields).toBe(builtin.ConfigFields);+ expect(overridden.buildAdapterConfig).toBe(builtin.buildAdapterConfig);++ syncExternalAdapters([{ type, label: "External Hermes", overrideDisabled: true }]);++ expect(getUIAdapter(type)).toBe(builtin);++ syncExternalAdapters([{ type, label: "External Hermes" }]);+ expect(getUIAdapter(type)).not.toBe(builtin);++ syncExternalAdapters([]);++ expect(getUIAdapter(type)).toBe(builtin);+ }+ });});diff --git a/ui/src/adapters/registry.ts b/ui/src/adapters/registry.tsindex 9b2476d3c8..d698e86b31 100644--- a/ui/src/adapters/registry.ts+++ b/ui/src/adapters/registry.ts@@ -6,10 +6,11 @@ import { cursorCloudUIAdapter } from "./cursor-cloud";import { cursorLocalUIAdapter } from "./cursor";import { geminiLocalUIAdapter } from "./gemini-local";import { grokLocalUIAdapter } from "./grok-local";+import { hermesGatewayUIAdapter } from "./hermes-gateway";+import { hermesLocalUIAdapter } from "./hermes-local";import { openCodeLocalUIAdapter } from "./opencode-local";import { piLocalUIAdapter } from "./pi-local";import { openClawGatewayUIAdapter } from "./openclaw-gateway";-import { hermesLocalUIAdapter } from "./hermes-local";import { processUIAdapter } from "./process";import { httpUIAdapter } from "./http";import { loadDynamicParser, invalidateDynamicParser, setDynamicParserResultNotifier } from "./dynamic-loader";@@ -58,6 +59,7 @@ function registerBuiltInUIAdapters() {cursorCloudUIAdapter,geminiLocalUIAdapter,grokLocalUIAdapter,+ hermesGatewayUIAdapter,hermesLocalUIAdapter,openCodeLocalUIAdapter,piLocalUIAdapter,diff --git a/ui/src/adapters/use-adapter-capabilities.ts b/ui/src/adapters/use-adapter-capabilities.tsindex 89f2c2b6c4..14e466e67a 100644--- a/ui/src/adapters/use-adapter-capabilities.ts+++ b/ui/src/adapters/use-adapter-capabilities.ts@@ -24,7 +24,6 @@ const KNOWN_DEFAULTS: Record<string, AdapterCapabilities> = {grok_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: false },opencode_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: true },pi_local: { supportsInstructionsBundle: true, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: true, supportsModelProfiles: false },- hermes_local: { supportsInstructionsBundle: false, supportsSkills: true, supportsLocalAgentJwt: true, requiresMaterializedRuntimeSkills: false, supportsModelProfiles: false },openclaw_gateway: ALL_FALSE,};diff --git a/ui/src/api/agents.ts b/ui/src/api/agents.tsindex fc29bac98e..45e134c3cd 100644--- a/ui/src/api/agents.ts+++ b/ui/src/api/agents.ts@@ -15,6 +15,7 @@ import type {Approval,AgentConfigRevision,ClearAgentErrorResponse,+ AgentApiKeyScope,} from "@paperclipai/shared";import type {AdapterModelProfileDefinition,@@ -26,6 +27,7 @@ import { ApiError, api } from "./client";export interface AgentKey {id: string;name: string;+ scope: AgentApiKeyScope;createdAt: Date;revokedAt: Date | null;}@@ -178,8 +180,8 @@ export const agentsApi = {api.get<AgentSkillSnapshot>(agentPath(id, companyId, "/skills")),syncSkills: (id: string, desiredSkills: Array<string | AgentDesiredSkillEntry>, companyId?: string) =>api.post<AgentSkillSnapshot>(agentPath(id, companyId, "/skills/sync"), { desiredSkills }),- createKey: (id: string, name: string, companyId?: string) =>- api.post<AgentKeyCreated>(agentPath(id, companyId, "/keys"), { name }),+ createKey: (id: string, name: string, companyId?: string, scope?: AgentApiKeyScope) =>+ api.post<AgentKeyCreated>(agentPath(id, companyId, "/keys"), { name, ...(scope ? { scope } : {}) }),revokeKey: (agentId: string, keyId: string, companyId?: string) =>api.delete<{ ok: true }>(agentPath(agentId, companyId, `/keys/${encodeURIComponent(keyId)}`)),runtimeState: (id: string, companyId?: string) =>diff --git a/ui/src/components/AgentConfigForm.tsx b/ui/src/components/AgentConfigForm.tsxindex 06f12521e9..1dafb6a6dc 100644--- a/ui/src/components/AgentConfigForm.tsx+++ b/ui/src/components/AgentConfigForm.tsx@@ -436,8 +436,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {const [refreshModelsError, setRefreshModelsError] = useState<string | null>(null);const [refreshingModels, setRefreshingModels] = useState(false);const rawModels = fetchedModels ?? externalModels ?? [];- const adapterCommandField =- adapterType === "hermes_local" ? "hermesCommand" : "command";+ const adapterCommandField = "command";const acpxAgent =adapterType === "acpx_local"? isCreate@@ -529,17 +528,6 @@ export function AgentConfigForm(props: AgentConfigFormProps) {if (adapterConfigPatch) {Object.assign(next, adapterConfigPatch);}- if (adapterType === "hermes_local") {- const hermesCommand =- typeof next.hermesCommand === "string" && next.hermesCommand.length > 0- ? next.hermesCommand- : typeof next.command === "string" && next.command.length > 0- ? next.command- : undefined;- if (hermesCommand) {- next.hermesCommand = hermesCommand;- }- }return next;}@@ -1201,9 +1189,7 @@ export function AgentConfigForm(props: AgentConfigFormProps) {"adapterConfig",adapterCommandField,String(- (adapterType === "hermes_local"- ? config.hermesCommand ?? config.command- : config.command) ?? "",+ config.command ?? "",),)}diff --git a/ui/src/components/HermesIcon.tsx b/ui/src/components/HermesIcon.tsxdeleted file mode 100644index fb02623a22..0000000000--- a/ui/src/components/HermesIcon.tsx+++ /dev/null@@ -1,43 +0,0 @@-import { cn } from "../lib/utils";--interface HermesIconProps {- className?: string;-}--/**- * Hermes caduceus icon — winged staff with two intertwined serpents.- * Replaces the generic Zap icon for the hermes_local adapter type.- *- * ⚕️ inspired but as the proper caduceus (Hermes' symbol): staff + two snakes + wings.- */-export function HermesIcon({ className }: HermesIconProps) {- return (- <svg- viewBox="0 0 24 24"- fill="none"- stroke="currentColor"- strokeWidth="1.5"- strokeLinecap="round"- strokeLinejoin="round"- className={cn(className)}- >- {/* Central staff */}- <line x1="12" y1="6" x2="12" y2="23" />- {/* Left serpent curves */}- <path d="M12 8 C10 9 9.5 11 10.5 13 C11.5 15 10 17 12 18" />- {/* Right serpent curves */}- <path d="M12 8 C14 9 14.5 11 13.5 13 C12.5 15 14 17 12 18" />- {/* Snake heads facing outward */}- <circle cx="10" cy="8" r="0.8" fill="currentColor" stroke="none" />- <circle cx="14" cy="8" r="0.8" fill="currentColor" stroke="none" />- {/* Wings at top of staff */}- <path d="M12 6 L8 3 L6 5 L9 6" strokeWidth="1.2" />- <path d="M12 6 L16 3 L18 5 L15 6" strokeWidth="1.2" />- {/* Wing feather details */}- <line x1="7.5" y1="4" x2="7" y2="5.2" strokeWidth="1" />- <line x1="16.5" y1="4" x2="17" y2="5.2" strokeWidth="1" />- {/* Staff sphere at top */}- <circle cx="12" cy="6.5" r="1.2" />- </svg>- );-}diff --git a/ui/src/components/OnboardingWizard.tsx b/ui/src/components/OnboardingWizard.tsxindex f7c6eaac08..b68a7de9bb 100644--- a/ui/src/components/OnboardingWizard.tsx+++ b/ui/src/components/OnboardingWizard.tsx@@ -271,7 +271,6 @@ export function OnboardingWizard() {adapterType === "claude_local" ||adapterType === "codex_local" ||adapterType === "gemini_local" ||- adapterType === "hermes_local" ||adapterType === "opencode_local" ||adapterType === "pi_local" ||adapterType === "cursor";@@ -298,7 +297,6 @@ export function OnboardingWizard() {claude_local: "claude",codex_local: "codex",gemini_local: "gemini",- hermes_local: "hermes",pi_local: "pi",cursor: "agent",opencode_local: "opencode",diff --git a/ui/src/lib/agent-onboarding-prompt.test.ts b/ui/src/lib/agent-onboarding-prompt.test.tsnew file mode 100644index 0000000000..1166fce2ad--- /dev/null+++ b/ui/src/lib/agent-onboarding-prompt.test.ts@@ -0,0 +1,26 @@+import { describe, expect, it } from "vitest";+import { buildAgentOnboardingPrompt } from "./agent-onboarding-prompt";++describe("buildAgentOnboardingPrompt", () => {+ it("includes Hermes Gateway setup guidance for external agents", () => {+ const prompt = buildAgentOnboardingPrompt({+ onboardingTextUrl: "http://localhost:3100/api/invites/token-123/onboarding.txt",+ connectionCandidates: ["http://192.168.1.10:3100"],+ });++ expect(prompt).toContain('adapterType: "hermes_gateway"');+ expect(prompt).toContain("API_SERVER_ENABLED=true");+ expect(prompt).toContain("API_SERVER_KEY");+ expect(prompt).toContain("hermes gateway run --replace --accept-hooks");+ expect(prompt).toContain("default Hermes API server port is `8642`");+ expect(prompt).toContain("agentDefaultsPayload.apiBaseUrl");+ expect(prompt).toContain("agentDefaultsPayload.paperclipApiUrl");+ expect(prompt).toContain("http://127.0.0.1:8642");+ expect(prompt).toContain("http://<private-ip>:8642");+ expect(prompt).toContain("http://<tailnet-host>:8642");+ expect(prompt).toContain("http://host.docker.internal:8642");+ expect(prompt).toContain("https://hermes-gateway.example");+ expect(prompt).toContain("`hermes_local` runs Hermes on the Paperclip host");+ expect(prompt).toContain("Hermes-originated Paperclip API calls");+ });+});diff --git a/ui/src/lib/agent-onboarding-prompt.ts b/ui/src/lib/agent-onboarding-prompt.tsindex bac83f4600..3da1b65967 100644--- a/ui/src/lib/agent-onboarding-prompt.ts+++ b/ui/src/lib/agent-onboarding-prompt.ts@@ -55,6 +55,13 @@ Join flow:OpenClaw Gateway note:If you are an OpenClaw Gateway agent, use \`adapterType: "openclaw_gateway"\`, set \`agentDefaultsPayload.url\` to your \`ws://\` or \`wss://\` gateway URL, and include \`agentDefaultsPayload.headers["x-openclaw-token"]\` with your gateway token. Do not use \`/v1/responses\` or \`/hooks/*\` in that join flow.+Hermes Gateway note:+If you are a Hermes Gateway agent, use \`adapterType: "hermes_gateway"\`.+- Start Hermes with \`API_SERVER_ENABLED=true\` and \`API_SERVER_KEY=<random-gateway-key>\`, then run \`hermes gateway run --replace --accept-hooks\`. The default Hermes API server port is \`8642\`.+- Set \`agentDefaultsPayload.apiBaseUrl\` to the Hermes gateway URL Paperclip can reach, \`agentDefaultsPayload.apiKey\` to the same value as \`API_SERVER_KEY\`, and \`agentDefaultsPayload.paperclipApiUrl\` to the Paperclip base URL Hermes can reach.+- \`apiBaseUrl\` examples: local loopback \`http://127.0.0.1:8642\`; LAN/private network \`http://<private-ip>:8642\`; private overlay \`http://<tailnet-host>:8642\`; Docker \`http://host.docker.internal:8642\`; reverse proxy/TLS \`https://hermes-gateway.example\`.+- Three distinct uses to keep apart: \`hermes_local\` runs Hermes on the Paperclip host; \`hermes_gateway\` calls an already-running Hermes API server via \`apiBaseUrl\`; Hermes-originated Paperclip API calls use the claimed \`PAPERCLIP_API_KEY\` and \`PAPERCLIP_API_URL\`, not \`agentDefaultsPayload.apiBaseUrl\`.+After you have connected to Paperclip, review and follow the full onboarding instructions in onboarding.txt.`;}